Opsdir review

[ioggstream]

Opsdir review

• [x] 1. Section 2

  For Media Type registration in section 2, I am not clear whether Macintosh file type code and Windows Clipboard Name should be mentioned as additional information?

The request came from the media type mailing list. They provided a reference to the the SVG media type registration that places this information under the Additional information. The related issue is here.

• [x] 2. Section 2.2

  For The +yaml Structured Syntax Suffix in section 2.2, how many contacts do we allowed? My impression, in most case, the single contact is preferred, wrong?

We used the same wording from the +xml SSS registration.

Agree with @darrelmiller as no-change. See https://github.com/ietf-wg-httpapi/mediatypes/issues/79#issuecomment-1509262222

• [x] 3.Section 3.1 said:

  “ While this document is based on a given YAML version [YAML], the media type registration does not imply a specific version. This allows content negotiation of version-independent YAML resources.

  Implementers concerned about features related to a specific YAML version can specify it in YAML documents using the %YAML directive (see Section 6.8.1 of [YAML]). ” It looks these two paragraphs contradict to each other, if we see features related to a specific YAML version as some kind of YAML resource, should we also allow content negotiation of version specific YAML resources? Correct me if I am wrong?

This point was discussed with the YAML community, and there is not an easy solution since a YAML resource could theoretically contain different YAML documents each with its own version (see the example below: we didn't add it to the document to avoid fostering this kind of practice). The current wording tries to keep things simple while warning implementers of possible issues.

%YAML 1.2
---
a: 1
...
%YAML 1.1
---
b: 1
...

We propose the following edit in #86

This [YAML] media type registration is independent of YAML version.

• [x] 4. Section 3.2 said:

  “ When receiving a multi-document stream, an application that only expects one-document streams, ought to signal an error instead of ignoring the extra documents.

  Current implementations consider different documents in a stream independent, similarly to JSON Text Sequences (see [RFC7464]); elements such as anchors are not guaranteed to be referenceable across different documents.

  ” I am a little confused here, Is current implementations documented by this draft? Or new implementation related to this draft should consider different document in a stream dependently or can detect whether a single document or multiple documents are carried in a stream?

Foreword: a "YAML stream" is just the formal name of a YAML resource, that can contain one or more documents separated by ---.

The current YAML specifications (and thus, implementations) consider different documents in a stream as independent. Since during the editorial work there were some doubts on the correct behavior, we decided to clarify this in the Interoperability Considerations.

I also suggest we should leave how to signal an error beyond the scope of this document.

While the I-D does not specify "how" to signal an error, just that raising an error is an interoperable behavior. We explicitly avoid using normative clauses here, and used "ought" instead. Do you see any drawbacks in this?

• [x] 5. Section 3.4 figure 3

  Not clear whether figure 3 in section 3.4 should be moved to Appendix A. Or some figure in appendix A should be moved to section 3.4, e.g., One interoperability issue， i.e., mapping keys that are not strings is clearly related to appendix A.1

See @eemeli 's comment. I agree with it. https://github.com/ietf-wg-httpapi/mediatypes/issues/79#issuecomment-1506517453

• [x] 6. Nits

  s/ when trying to serialize it JSON/ when trying to serialize it in JSON s/ representaion graph/ representation graph s/ can infinite-loop traversing the YAML representation graph/ can fall into infinite-loop traversing the YAML representation graph

Already fixed.

[eemeli]

Not clear whether figure 3 in section 3.4 should be moved to Appendix A. Or some figure in appendix A should be moved to section 3.4, e.g., One interoperability issue， i.e., mapping keys that are not strings is clearly related to appendix A.1

I think the current place for this figure is appropriate. Non-string mapping keys are a cause of interoperability issues with JSON as well as pathlike fragment identifiers. However, the interoperability issues are not the exact same set for the two. For instance, with a YAML document that contains just the first part of the example:

non-json-keys:
   0: a number

The a number value is addressable as #/non-json-keys/0, but the JSON representation of the same document:

{
  "non-json-keys":
    { "0": "a number" }
}

explicitly casts the 0 as a string, rather than allowing for it to be parsed as a number by a YAML schema that supports such.

[darrelmiller]

@ioggstream The current registration process says that a contact is a "person". https://www.rfc-editor.org/rfc/rfc6838.html#section-6.2 However, looking at the current registry https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml there appears to be a range of different entries that do not meet the definition of a person. The proposal in the current YAML draft seems aligned with other registrations, and so I see no reason to change it.

While this document is based on a given YAML version [YAML], the media type registration does not imply a specific version. This allows content negotiation of version-independent YAML resources.

This paragraph confused me when I read it the first couple of times. Would it be simpler to simply say:

This [YAML] media type registration is independent of YAML version. This allows content negotiation of version-independent YAML resources.

[ioggstream]

Closed via #76