diff --git a/draft-ietf-httpapi-rest-api-mediatypes.md b/draft-ietf-httpapi-rest-api-mediatypes.md index 7f32722..ee2be95 100644 --- a/draft-ietf-httpapi-rest-api-mediatypes.md +++ b/draft-ietf-httpapi-rest-api-mediatypes.md @@ -106,6 +106,9 @@ The OpenAPI Specification Media Types convey semantics for OpenAPI Document (OAD as defined in [OAS] for version 3.0 and above. Those resources can be represented in {{JSON}} or [YAML]. + +### The version parameter + Since there are multiple OpenAPI Specification versions, those media types support the `version` parameter. @@ -124,6 +127,54 @@ Accept: application/openapi+yaml;version=3.1, application/openapi+json;q=0.3 ~~~ +### The component parameter + +The optional `component` parameter indicates that the conveyed content +is not a complete OpenAPI Document. +Instead, it is a referenceable sub-part, (e.g., a single Schema Object, +or a Path Item Object). + +Valid values for the `component` parameter +are: + +- the star `*` character, indicating that the client + is willing to accept any component type as well as a complete OpenAPI Document; +- the camelCase names of the associated Object Types, +and depend on the OpenAPI version. +For example, the `component` parameter value for the +Path Item Object defined in OpenAPI 3.1 is `pathItem`, +while the `component` parameter value for the +Schema Object is `schema`. + +An example of a request that is willing to accept both +a complete OpenAPI Document and a Schema Object is: + +~~~ http-message + +GET /person.yaml +Accept: application/openapi+yaml, application/openapi+yaml;component=schema +~~~ +{:title "A request that is willing to accept either a complete openapi document or a Schema Object" } + +An example response returnning a Schema Object is: + +~~~ http-message +HTTP/1.1 200 OK +Content-Type: application/openapi+yaml;component=schema + +description: >- + This schema is enclosed in a separate file, + that is not a complete OpenAPI Document. +type: object +properties: + given_name: + type: string + family_name: + type: string + +~~~ +{:title "OpenAPI response} + ### Media Type application/openapi+json {#openapi-json} The following information serves as the registration form for the `application/openapi+json` media type. @@ -138,7 +189,7 @@ Required parameters: : None Optional parameters: -: version; unrecognized parameters should be ignored +: version, component; unrecognized parameters should be ignored. Encoding considerations: : Same as "application/json" @@ -147,7 +198,7 @@ Security considerations: : See {{security-considerations}} of this document, "application/json" and [OAS] Interoperability considerations: -: See "application/json" and [OAS] +: See "application/json", [OAS] and {{int}} Published specification: : this document, [OAS] @@ -198,7 +249,7 @@ Required parameters: : N/A Optional parameters: -: version; unrecognized parameters should be ignored +: version, component; unrecognized parameters should be ignored Encoding considerations: : Same as "+yaml" Structured Syntax Suffix @@ -207,7 +258,7 @@ Security considerations: : See {{security-considerations}} of this document, "+yaml" Structured Syntax Suffix and [OAS] Interoperability considerations: -: See "+yaml" Structured Syntax Suffix and [OAS] +: See "+yaml" Structured Syntax Suffix, [OAS] and {{int}} Published specification: : [OAS] @@ -245,12 +296,22 @@ Change controller: : IETF -# Interoperability Considerations +# Interoperability Considerations {#int} Interoperability requirements for media type registrations are discussed in Section 4.6 of {{!MEDIATYPE=RFC6838}}. and in the Interoperability Considerations of the "+yaml" Structured Syntax Suffix. +## Component Parameter {#int-component-parameter} + +The `component` parameter allows clients to request specific parts of an OpenAPI Document, +and enables servers to advertise clients that the content does not convey a complete OpenAPI Document. + +Current tools tend to process partial documents in the context of a complete document +(e.g., a referenced Schema Object in the context of the sourcing OpenAPI Document). +While the `component` parameter can be a hint for processing tools, +implementors interested in interoperability should be tolerant of the absence of the `component` parameter. + # Security Considerations Security requirements for media type @@ -309,6 +370,9 @@ Q: Why this document? This has some security implications too (eg. wrt on identifying parsers or treat downloads) +Q: Do we support OpenAPI 2.0 / Swagger? +: No, this document is about OpenAPI 3.0 and above. + # Change Log {: numbered="false" removeinrfc="true"}