Draft: draft-ietf-httpapi-rest-api-mediatypes

Commentary: splits application / yaml and + yaml in a new I - D 
 thx++ ! Do you like to be mentioned in the Acknowledgement section ? 
 It is a small edit , so no . Thanks for asking ! 
 application / yaml and + yaml to be addressed in a separate I - D so that it can go at a faster pace cc : 
 looks good to me , thanks !
This document registers the following media types used in APIs on the
IANA Media Types registry: application/yaml, application/schema+json,
application/schema-instance+json, application/openapi+json, and
application/openapi+yaml.
This document registers the following media types used in APIs on the
IANA Media Types registry: application/schema+json, application/
schema-instance+json, application/openapi+json, and application/
openapi+yaml.
To increase interoperability when processing API specifications and
leverage content negotiation mechanisms when exchanging OpenAPI
Specification resources this specification register the following
media-types: "application/yaml", "application/schema+json",
"application/schema-instance+json", "application/openapi+json" and
"application/openapi+yaml".
Moreover it defines and registers the "+yaml" structured syntax
suffix.
YAML media type registration is addressed in YAML-MEDIATYPES, which
provides interoperability and security considerations.
To increase interoperability when processing API specifications and
leverage content negotiation mechanisms when exchanging OpenAPI
Specification resources this specification register the following
media-types: "application/schema+json", "application/schema-
instance+json", "application/openapi+json" and "application/
openapi+yaml".
The following information serves as the registration form for the
"application/yaml" media type.
Person and email address to contact for further information: See
Authors' Addresses section.
Restrictions on usage: None.
Author: See Authors' Addresses section.
The suffix "+yaml" MAY be used with any media type whose
representation follows that established for "application/yaml".  The
media type structured syntax suffix registration form follows.  See
MEDIATYPE for definitions of each of the registration form headings.
Contact: See Authors' Addresses section.
YAML is an evolving language and, in time, some features have been
added, and others removed.
While this document is based on a given YAML version YAML, media
types 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 the documents using the "%YAML" directive
(see Section 6.8.1 of YAML).
When using flow collection styles (see Section 7.4 of YAML) a YAML
document could look like JSON JSON, thus similar interoperability
considerations apply.
When using YAML as a more efficient format to serialize information
intented to be consumed as JSON, information can be discarded: this
includes comments (see Section 3.2.3.3 of YAML) and alias nodes (see
Section 7.1 of YAML), that do not have a JSON counterpart.
Implementers need to ensure that relevant information will not be
lost during the processing.  For example, they might consider
acceptable that alias nodes are replaced by static values.
circular references represented using anchor (see sec-yaml-
exhaustion and example-yaml-cyclic).
Security requirements for both media type and media type suffix
registrations are discussed in Section 4.6 of MEDIATYPE.
Care should be used when using YAML tags, because their
implementation might trigger unexpected code execution.
Code execution in deserializers should be disabled by default, and
only be enabled explicitly.  In those cases, the implementation
should ensure - for example, via specific functions - that the code
execution results in strictly bounded time/memory limits.
Many implementations provide safe deserializers addressing these
issues.
YAML documents are rooted, connected, directed graphs and can contain
reference cycles, so they can't be treated as simple trees (see
Section 3.2.1 of YAML).  An implementation that attempts to do that
can infinite-loop at some point (e.g. when trying to serialize a YAML
document in JSON).
Even if a document is not cyclic, treating it as a tree could lead to
improper behaviors (such as the "billion laughs" problem).
This can be addressed using processors limiting the anchor recursion
depth and validating the input before processing it; even in these
cases it is important to carefully test the implementation you are
going to use.  The same considerations apply when serializing a YAML
representation graph in a format that do not support reference cycles
(see int-yaml-and-json).
Interoperability requirements for media type registrations are
discussed in Section 4.6 of MEDIATYPE.  and YAML-MEDIATYPES.
Security requirements for media type registrations are discussed in
Section 4.6 of MEDIATYPE.  and YAML-MEDIATYPES.
IANA has updated the "Structured Syntax Suffixes" registry at
https://www.iana.org/assignments/media-type-structured-suffix [4]
with the registration information provided below.