From 607e5d70111048056e34dbf275cc46aa8117fda5 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 16 May 2025 16:32:00 +0100 Subject: [PATCH 01/28] Start with a list of changes --- draft-release-notes.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 draft-release-notes.md diff --git a/draft-release-notes.md b/draft-release-notes.md new file mode 100644 index 0000000000..f9233afe90 --- /dev/null +++ b/draft-release-notes.md @@ -0,0 +1,42 @@ +# [DRAFT]: Release Notes + +What's coming up? Look at `src/oas.md` on the relevant development branch for full details. + +## 3.2 Updates + + +- **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in links object +- Sequential media types: + - Support for sequential mediatypes such as text/event-stream for server-sent events (SSE) and application/jsonl, application/json-seq and others for sequential data. + - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. + - Use itemSchema in a mediatype entry to describe each item + - Related: a new media types registry is published to give more context for each of the media types + - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads +- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow +- Servers: + - clarify that server URLs should not include fragment or query. + - support new`name` field alongside description, url and variables + - formal path templating support for variable substitution in server urls +- Methods: + - support the new `query` operation alongside get/post/put/delete/options/head/patch/trace + - under an additionalOperations entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` +- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data, +- Description field for responses are now optional (they used to be required but they could be empty) +- Tags + - new summary field to match other things + - parent field to allow hierarchy + - kind to allow multiple categories of tag +- Discriminator - helps with API evolution (?) + - use discriminator to hint which anyOf or oneOf is expected + - discriminator propertyName MUST be defined but the field it points to MAY be optional - in which case a defaultMapping MUST be defined + - the mapping should be defined if the discriminator property value doesn't match the Schema name + - new field: `defaultMapping` means that if the discriminator field doesn't have a value, which mapping value to use +- XML namespaces can be IRIs (rather than URIs) +- Security: + - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl` + - additional security scheme field: oauth2MetadataUrl URL for auth server metadata + - additional field to mark security schemes as deprecated (so don't use it for new stuff, but maybe still supported/valid) + - can reference a security scheme by URI rather than needing it declared in components. + +## 3.2 Updates + From ad61ff84c8a941cde672cfecb45657baeb5b9e5e Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 16 May 2025 17:34:39 +0100 Subject: [PATCH 02/28] Add notes for 3.1, sort out formatting, add updated references --- draft-release-notes.md | 56 +++++++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 23 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index f9233afe90..49c6c44645 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -4,39 +4,49 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu ## 3.2 Updates - - **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in links object - Sequential media types: - - Support for sequential mediatypes such as text/event-stream for server-sent events (SSE) and application/jsonl, application/json-seq and others for sequential data. - - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - - Use itemSchema in a mediatype entry to describe each item - - Related: a new media types registry is published to give more context for each of the media types - - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads + - Support for sequential mediatypes such as text/event-stream for server-sent events (SSE) and application/jsonl, application/json-seq and others for sequential data. + - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. + - Use itemSchema in a mediatype entry to describe each item + - Related: a new media types registry is published to give more context for each of the media types + - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow - Servers: - - clarify that server URLs should not include fragment or query. - - support new`name` field alongside description, url and variables - - formal path templating support for variable substitution in server urls + - clarify that server URLs should not include fragment or query. + - support new`name` field alongside description, url and variables + - formal path templating support for variable substitution in server urls - Methods: - - support the new `query` operation alongside get/post/put/delete/options/head/patch/trace - - under an additionalOperations entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` + - support the new `query` operation alongside get/post/put/delete/options/head/patch/trace + - under an additionalOperations entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data, - Description field for responses are now optional (they used to be required but they could be empty) - Tags - - new summary field to match other things - - parent field to allow hierarchy - - kind to allow multiple categories of tag + - new summary field to match other things + - parent field to allow hierarchy + - kind to allow multiple categories of tag + - a registry for some common categories (but any value can be used) - Discriminator - helps with API evolution (?) - - use discriminator to hint which anyOf or oneOf is expected - - discriminator propertyName MUST be defined but the field it points to MAY be optional - in which case a defaultMapping MUST be defined - - the mapping should be defined if the discriminator property value doesn't match the Schema name - - new field: `defaultMapping` means that if the discriminator field doesn't have a value, which mapping value to use + - use discriminator to hint which anyOf or oneOf is expected + - discriminator propertyName MUST be defined but the field it points to MAY be optional - in which case a defaultMapping MUST be defined + - the mapping should be defined if the discriminator property value doesn't match the Schema name + - new field: `defaultMapping` means that if the discriminator field doesn't have a value, which mapping value to use - XML namespaces can be IRIs (rather than URIs) - Security: - - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl` - - additional security scheme field: oauth2MetadataUrl URL for auth server metadata - - additional field to mark security schemes as deprecated (so don't use it for new stuff, but maybe still supported/valid) - - can reference a security scheme by URI rather than needing it declared in components. + - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl` + - additional security scheme field: oauth2MetadataUrl URL for auth server metadata + - additional field to mark security schemes as deprecated (so don't use it for new stuff, but maybe still supported/valid) + - can reference a security scheme by URI rather than needing it declared in components. +- In-place updates to existing specifications and standards that we reference: + - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification + - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification + - Use [RFC8529]((https://tools.ietf.org/html/rfc8259) for JSON + - Use [RFC9110]((https://tools.ietf.org/html/rfc9110) for HTTP -## 3.2 Updates +## 3.1 Updates + +Version 3.1.2 has no material changes but does contain editorial fixes. + +- Clarification that Example Objects can be used in Header Objects. +- Better explanation and examples for using Encoding. From 74c7289a2ead99779d6455a566a976ff6322796c Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sat, 24 May 2025 20:00:55 +0100 Subject: [PATCH 03/28] Update structure and improve wording --- draft-release-notes.md | 66 ++++++++++++++++++++++++++++-------------- 1 file changed, 45 insertions(+), 21 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 49c6c44645..4648b67569 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -4,49 +4,73 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu ## 3.2 Updates -- **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in links object -- Sequential media types: - - Support for sequential mediatypes such as text/event-stream for server-sent events (SSE) and application/jsonl, application/json-seq and others for sequential data. - - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - - Use itemSchema in a mediatype entry to describe each item - - Related: a new media types registry is published to give more context for each of the media types - - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads -- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow -- Servers: - - clarify that server URLs should not include fragment or query. - - support new`name` field alongside description, url and variables - - formal path templating support for variable substitution in server urls - Methods: - support the new `query` operation alongside get/post/put/delete/options/head/patch/trace - under an additionalOperations entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` -- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data, -- Description field for responses are now optional (they used to be required but they could be empty) + - Tags - new summary field to match other things - parent field to allow hierarchy - kind to allow multiple categories of tag - a registry for some common categories (but any value can be used) -- Discriminator - helps with API evolution (?) - - use discriminator to hint which anyOf or oneOf is expected - - discriminator propertyName MUST be defined but the field it points to MAY be optional - in which case a defaultMapping MUST be defined - - the mapping should be defined if the discriminator property value doesn't match the Schema name - - new field: `defaultMapping` means that if the discriminator field doesn't have a value, which mapping value to use -- XML namespaces can be IRIs (rather than URIs) + - Security: - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl` - - additional security scheme field: oauth2MetadataUrl URL for auth server metadata + - additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata - additional field to mark security schemes as deprecated (so don't use it for new stuff, but maybe still supported/valid) - can reference a security scheme by URI rather than needing it declared in components. + +- Servers: + - clarify that server URLs should not include fragment or query. + - support new`name` field alongside description, url and variables + - formal path templating support for variable substitution in server urls + +- Discriminator + - use discriminator to hint which anyOf or oneOf is expected (existing functionality) + - discriminator `propertyName` MUST be defined but the named field can be optional (previously was required) + - use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match (existing functionality) + - new field: `defaultMapping` says which schema to use if the `propertyName` is not set, or if the value is unrecognized + +- **ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. + +Improvements for APIs using XML as a content format: + - XML namespaces can be IRIs (rather than URIs) + - Explanation and example on how to handle `null` in XML + +- Sequential media types: + - Support for sequential mediatypes such as text/event-stream for server-sent events (SSE) and application/jsonl, application/json-seq and others for sequential data. + - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. + - Use itemSchema in a mediatype entry to describe each item + - Related: a new media types registry is published to give more context for each of the media types + - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads + +Minor edits that are worth a mention: + - Description field for responses are now optional (they used to be required but they could be empty) + - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow + - `allowReserved` is now supported for any parameter or header, regardless of `in` location + - In-place updates to existing specifications and standards that we reference: - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification - Use [RFC8529]((https://tools.ietf.org/html/rfc8259) for JSON - Use [RFC9110]((https://tools.ietf.org/html/rfc9110) for HTTP +- Editorial changes: + - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data, + - Clarification that Example Objects can be used in Header Objects. + - Better explanation and examples for using Encoding. + - Clarify that Request Body Objects need to specify at least one media type to be meaningful + - How to more clearly indicate that responses will not have a body + + ## 3.1 Updates Version 3.1.2 has no material changes but does contain editorial fixes. - Clarification that Example Objects can be used in Header Objects. - Better explanation and examples for using Encoding. +- Clarify that Request Body Objects need to specify at least one media type to be meaningful +- How to more clearly indicate that no response will have a body +- How to handle `null` in XML + From 4b8e237bf7fda92333076eac8763a737db077dc3 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 28 May 2025 12:15:26 +0100 Subject: [PATCH 04/28] Update draft-release-notes.md Co-authored-by: Vincent Biret --- draft-release-notes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 4648b67569..7c6340ba30 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -52,8 +52,8 @@ Minor edits that are worth a mention: - In-place updates to existing specifications and standards that we reference: - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification - - Use [RFC8529]((https://tools.ietf.org/html/rfc8259) for JSON - - Use [RFC9110]((https://tools.ietf.org/html/rfc9110) for HTTP + - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON + - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP - Editorial changes: - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data, From 6c82362ea32ca3fb55d18cce13c9461af0f99d21 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 1 Jun 2025 09:39:59 +0100 Subject: [PATCH 05/28] Update draft-release-notes.md Co-authored-by: Ralf Handl --- draft-release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 7c6340ba30..a41eda3722 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -6,7 +6,7 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Methods: - support the new `query` operation alongside get/post/put/delete/options/head/patch/trace - - under an additionalOperations entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` + - under an `additionalOperations` entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` - Tags - new summary field to match other things From 55b604a4b1df133679d7c83a8226e31773e340b3 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 1 Jun 2025 09:55:50 +0100 Subject: [PATCH 06/28] Sort out some formatting and suggested improvements --- draft-release-notes.md | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index a41eda3722..1542b1a18f 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -9,43 +9,43 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - under an `additionalOperations` entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` - Tags - - new summary field to match other things - - parent field to allow hierarchy - - kind to allow multiple categories of tag - - a registry for some common categories (but any value can be used) + - new `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. + - `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy. + - `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). + - a [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. - Security: - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl` - additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata - - additional field to mark security schemes as deprecated (so don't use it for new stuff, but maybe still supported/valid) - - can reference a security scheme by URI rather than needing it declared in components. + - additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used) + - ability to reference a security scheme by URI rather than needing it declared in components. - Servers: - clarify that server URLs should not include fragment or query. - - support new`name` field alongside description, url and variables - - formal path templating support for variable substitution in server urls + - support new `name` field alongside `description`, `url` and `variables`. + - formal path templating support for variable substitution in server urls. - Discriminator - - use discriminator to hint which anyOf or oneOf is expected (existing functionality) - - discriminator `propertyName` MUST be defined but the named field can be optional (previously was required) - - use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match (existing functionality) - - new field: `defaultMapping` says which schema to use if the `propertyName` is not set, or if the value is unrecognized + - no change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. + - no change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. + - the discriminator `propertyName` can now be an optional field. + - additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. - **ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. -Improvements for APIs using XML as a content format: +- Improvements for APIs using XML as a content format: - XML namespaces can be IRIs (rather than URIs) - Explanation and example on how to handle `null` in XML - Sequential media types: - - Support for sequential mediatypes such as text/event-stream for server-sent events (SSE) and application/jsonl, application/json-seq and others for sequential data. + - Support for sequential mediatypes such as `text/event-stream` for server-sent events (SSE) and `application/jsonl`, `application/json-seq` and others for sequential data. - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - - Use itemSchema in a mediatype entry to describe each item + - Use `itemSchema` in a mediatype entry to describe each item - Related: a new media types registry is published to give more context for each of the media types - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads Minor edits that are worth a mention: - - Description field for responses are now optional (they used to be required but they could be empty) + - The `description` field for responses are now optional (they used to be required but they could be empty) - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow - `allowReserved` is now supported for any parameter or header, regardless of `in` location @@ -62,7 +62,6 @@ Minor edits that are worth a mention: - Clarify that Request Body Objects need to specify at least one media type to be meaningful - How to more clearly indicate that responses will not have a body - ## 3.1 Updates Version 3.1.2 has no material changes but does contain editorial fixes. From 5b290575f3593c35fef9ca49d9b49e75acb9d11f Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 1 Jun 2025 10:32:51 +0100 Subject: [PATCH 07/28] Add some more recent spec additions, use section headings --- draft-release-notes.md | 52 +++++++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 1542b1a18f..eccaba6229 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -4,58 +4,83 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu ## 3.2 Updates -- Methods: +### Methods + - support the new `query` operation alongside get/post/put/delete/options/head/patch/trace - under an `additionalOperations` entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` -- Tags +### Tags + - new `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. - `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy. - `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). - a [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. -- Security: +### Security + - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl` - additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata - additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used) - ability to reference a security scheme by URI rather than needing it declared in components. -- Servers: +### Servers + - clarify that server URLs should not include fragment or query. - support new `name` field alongside `description`, `url` and `variables`. - formal path templating support for variable substitution in server urls. -- Discriminator +### Discriminator + - no change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. - no change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. - the discriminator `propertyName` can now be an optional field. - additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. -- **ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. +### Reference resolution + + - additional top-level `$self` to be used as a base URI for resolving references in the OpenAPI description. If not present, the existing/earlier behaviour of using the retrieval URL as a base applies. + +### **ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. + +### Improvements for APIs using XML as a content format -- Improvements for APIs using XML as a content format: - XML namespaces can be IRIs (rather than URIs) - Explanation and example on how to handle `null` in XML + Clarify that the root schema of an XML object should use the component name. + +### Sequential media type -- Sequential media types: - Support for sequential mediatypes such as `text/event-stream` for server-sent events (SSE) and `application/jsonl`, `application/json-seq` and others for sequential data. - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - Use `itemSchema` in a mediatype entry to describe each item - Related: a new media types registry is published to give more context for each of the media types - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads -Minor edits that are worth a mention: - - The `description` field for responses are now optional (they used to be required but they could be empty) +### Parameters + + - additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. + - parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. + - `allowReserved` field is now permitted on parameters with any value of `in` (however this many not be a Good Idea (TM) in some scenarios) + +### Responses + + - `description` field for responses are now optional (they used to be required but they could be empty) + - additional `summary` field for responses, useful when displaying responses in a list context + +### Minor edits that are worth a mention: + - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow - `allowReserved` is now supported for any parameter or header, regardless of `in` location -- In-place updates to existing specifications and standards that we reference: +### In-place updates to existing specifications and standards that we reference: + - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP -- Editorial changes: +### Editorial changes: + - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data, - Clarification that Example Objects can be used in Header Objects. - Better explanation and examples for using Encoding. @@ -70,6 +95,7 @@ Version 3.1.2 has no material changes but does contain editorial fixes. - Better explanation and examples for using Encoding. - Clarify that Request Body Objects need to specify at least one media type to be meaningful - How to more clearly indicate that no response will have a body -- How to handle `null` in XML +- How to handle `null` in XML as an advisory note; since the functionality cannot be changed it is implementation-defined for 3.1 tooling. +- Clarify that the root schema of an XML object should use the component name. From a0323b8bcd92c706bbe0484976d9aa263ff8ccd6 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 8 Jul 2025 17:21:26 +0100 Subject: [PATCH 08/28] Apply suggestions from code review Co-authored-by: Henry Andrews --- draft-release-notes.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index eccaba6229..d00cebeea1 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -29,12 +29,13 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - support new `name` field alongside `description`, `url` and `variables`. - formal path templating support for variable substitution in server urls. -### Discriminator +### Code Generation - - no change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. - - no change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. - the discriminator `propertyName` can now be an optional field. - additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. + - no change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. + - no change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. + - Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef` ### Reference resolution @@ -44,6 +45,10 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu ### Improvements for APIs using XML as a content format + - New `nodeType` field allows maping schemas to all common XML node types (elements, attributes, text, or cdata) or to nothing + - `attribute: true` deprecated in favor of `nodeType: attribute` + - `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility) + - The `xml` keyword can be used in any Schema Object - XML namespaces can be IRIs (rather than URIs) - Explanation and example on how to handle `null` in XML Clarify that the root schema of an XML object should use the component name. @@ -56,11 +61,11 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Related: a new media types registry is published to give more context for each of the media types - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads -### Parameters +### Parameters and Headers - additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. - parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. - - `allowReserved` field is now permitted on parameters with any value of `in` (however this many not be a Good Idea (TM) in some scenarios) + - `allowReserved` field is now permitted on parameters and headers with any value of `in` (however this many not be a Good Idea (TM) in some scenarios) ### Responses From 02ad9800f4aee7a60fdfca9a859758819c9098a5 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 8 Jul 2025 20:56:27 +0100 Subject: [PATCH 09/28] Bring up to date, improve titles and formatting --- draft-release-notes.md | 108 +++++++++++++++++++++-------------------- 1 file changed, 55 insertions(+), 53 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index d00cebeea1..31ef73b60e 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -4,93 +4,95 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu ## 3.2 Updates -### Methods +### Support additional HTTP methods - - support the new `query` operation alongside get/post/put/delete/options/head/patch/trace - - under an `additionalOperations` entry, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head` + - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. + - Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head`. -### Tags +### Nested, multipurpose tags - - new `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. + - New `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. - `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy. - `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). - - a [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. + - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. -### Security +### Updated security schemes - - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl` - - additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata - - additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used) - - ability to reference a security scheme by URI rather than needing it declared in components. + - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. + - Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata. + - Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). + - Ability to reference a security scheme by URI rather than needing it declared in components. ### Servers - - clarify that server URLs should not include fragment or query. - - support new `name` field alongside `description`, `url` and `variables`. - - formal path templating support for variable substitution in server urls. + - Clarify that server URLs should not include fragment or query. + - Support new `name` field alongside `description`, `url` and `variables`. + - Formal path templating support for variable substitution in server urls. -### Code Generation +### Better polymorphic support - - the discriminator `propertyName` can now be an optional field. - - additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. - - no change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. - - no change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. - - Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef` + - The discriminator `propertyName` can now be an optional field. + - Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. + - No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. + - No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. + - Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. ### Reference resolution - - additional top-level `$self` to be used as a base URI for resolving references in the OpenAPI description. If not present, the existing/earlier behaviour of using the retrieval URL as a base applies. +Additional top-level `$self` to be used as a base URI for resolving references in the OpenAPI description. If not present, the existing/earlier behaviour of using the retrieval URL as a base applies. -### **ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. +### Path templating + +**ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. ### Improvements for APIs using XML as a content format - - New `nodeType` field allows maping schemas to all common XML node types (elements, attributes, text, or cdata) or to nothing - - `attribute: true` deprecated in favor of `nodeType: attribute` - - `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility) - - The `xml` keyword can be used in any Schema Object - - XML namespaces can be IRIs (rather than URIs) - - Explanation and example on how to handle `null` in XML - Clarify that the root schema of an XML object should use the component name. + - New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. + - `attribute: true` deprecated in favor of `nodeType: attribute`. + - `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). + - The `xml` keyword can be used in any Schema Object. + - XML namespaces can be IRIs (rather than URIs). + - Explanation and example on how to handle `null` in XML. + - Clarify that the root schema of an XML object should use the component name. -### Sequential media type +### Support for sequential media types - - Support for sequential mediatypes such as `text/event-stream` for server-sent events (SSE) and `application/jsonl`, `application/json-seq` and others for sequential data. + - Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `application/jsonl`, `application/json-seq` and others for sequential data. - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - - Use `itemSchema` in a mediatype entry to describe each item - - Related: a new media types registry is published to give more context for each of the media types - - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads + - Use `itemSchema` in a mediatype entry to describe each item. + - Related: a new media types registry is published to give more context for each of the media types. + - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads. -### Parameters and Headers +### Parameter and header changes - - additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. - - parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. - - `allowReserved` field is now permitted on parameters and headers with any value of `in` (however this many not be a Good Idea (TM) in some scenarios) + - Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. + - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. + - `allowReserved` field is now permitted on headers and on parameters with any value of `in` (however this many not be a Good Idea (TM) in some scenarios). + - Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. -### Responses +### Flexible response metadata fields - - `description` field for responses are now optional (they used to be required but they could be empty) - - additional `summary` field for responses, useful when displaying responses in a list context + - `description` field for responses are now optional (they used to be required but they could be empty). + - Additional `summary` field for responses, useful when displaying responses in a list context. -### Minor edits that are worth a mention: +### Minor edits that are worth a mention - - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow - - `allowReserved` is now supported for any parameter or header, regardless of `in` location + - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. -### In-place updates to existing specifications and standards that we reference: +### In-place updates to existing specifications and standards that we reference - - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification - - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification - - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON - - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP + - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification. + - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification. + - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. + - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. -### Editorial changes: +### Editorial changes - - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data, + - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. - Clarification that Example Objects can be used in Header Objects. - Better explanation and examples for using Encoding. - - Clarify that Request Body Objects need to specify at least one media type to be meaningful - - How to more clearly indicate that responses will not have a body + - Clarify that Request Body Objects need to specify at least one media type to be meaningful. + - How to more clearly indicate that responses will not have a body. ## 3.1 Updates From 248cfc92cc15c25876c96ae6e9e0668b26e63528 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 8 Jul 2025 21:01:57 +0100 Subject: [PATCH 10/28] Reformat and remove aside --- draft-release-notes.md | 96 +++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 31ef73b60e..01169933b2 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -6,36 +6,36 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu ### Support additional HTTP methods - - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. - - Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head`. +- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. +- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head`. ### Nested, multipurpose tags - - New `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. - - `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy. - - `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). - - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. +- New `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. +- `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy. +- `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). +- A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. ### Updated security schemes - - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. - - Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata. - - Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). - - Ability to reference a security scheme by URI rather than needing it declared in components. +- Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. +- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata. +- Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). +- Ability to reference a security scheme by URI rather than needing it declared in components. -### Servers +### Servers - - Clarify that server URLs should not include fragment or query. - - Support new `name` field alongside `description`, `url` and `variables`. - - Formal path templating support for variable substitution in server urls. +- Clarify that server URLs should not include fragment or query. +- Support new `name` field alongside `description`, `url` and `variables`. +- Formal path templating support for variable substitution in server urls. ### Better polymorphic support - - The discriminator `propertyName` can now be an optional field. - - Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. - - No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. - - No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. - - Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. +- The discriminator `propertyName` can now be an optional field. +- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. +- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. +- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. +- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. ### Reference resolution @@ -47,52 +47,52 @@ Additional top-level `$self` to be used as a base URI for resolving references i ### Improvements for APIs using XML as a content format - - New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. - - `attribute: true` deprecated in favor of `nodeType: attribute`. - - `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). - - The `xml` keyword can be used in any Schema Object. - - XML namespaces can be IRIs (rather than URIs). - - Explanation and example on how to handle `null` in XML. - - Clarify that the root schema of an XML object should use the component name. +- New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. +- `attribute: true` deprecated in favor of `nodeType: attribute`. +- `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). +- The `xml` keyword can be used in any Schema Object. +- XML namespaces can be IRIs (rather than URIs). +- Explanation and example on how to handle `null` in XML. +- Clarify that the root schema of an XML object should use the component name. ### Support for sequential media types - - Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `application/jsonl`, `application/json-seq` and others for sequential data. - - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - - Use `itemSchema` in a mediatype entry to describe each item. - - Related: a new media types registry is published to give more context for each of the media types. - - Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads. +- Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `application/jsonl`, `application/json-seq` and others for sequential data. +- Responses can be a repeating data structure, and are treated as if they are an array of schema objects. +- Use `itemSchema` in a mediatype entry to describe each item. +- Related: a new media types registry is published to give more context for each of the media types. +- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads. ### Parameter and header changes - - Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. - - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. - - `allowReserved` field is now permitted on headers and on parameters with any value of `in` (however this many not be a Good Idea (TM) in some scenarios). - - Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. - +- Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. +- Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. +- `allowReserved` field is now permitted on headers and on parameters with any value of `in`. +- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. + ### Flexible response metadata fields - - `description` field for responses are now optional (they used to be required but they could be empty). - - Additional `summary` field for responses, useful when displaying responses in a list context. +- `description` field for responses are now optional (they used to be required but they could be empty). +- Additional `summary` field for responses, useful when displaying responses in a list context. ### Minor edits that are worth a mention - - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. +- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. ### In-place updates to existing specifications and standards that we reference - - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification. - - Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification. - - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. - - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. +- Update to of JSON Schema Specification. +- Update to of JSON Schema Validation Specification. +- Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. +- Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. ### Editorial changes - - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. - - Clarification that Example Objects can be used in Header Objects. - - Better explanation and examples for using Encoding. - - Clarify that Request Body Objects need to specify at least one media type to be meaningful. - - How to more clearly indicate that responses will not have a body. +- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. +- Clarification that Example Objects can be used in Header Objects. +- Better explanation and examples for using Encoding. +- Clarify that Request Body Objects need to specify at least one media type to be meaningful. +- How to more clearly indicate that responses will not have a body. ## 3.1 Updates From 2e9fcc2b9e3230e0d54cb27e8ab7f763fb8e100a Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 3 Aug 2025 20:32:54 +0100 Subject: [PATCH 11/28] Apply suggestions from code review Co-authored-by: Henry Andrews --- draft-release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 01169933b2..1bcd23a051 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -78,7 +78,7 @@ Additional top-level `$self` to be used as a base URI for resolving references i ### Minor edits that are worth a mention - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. - +- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case ### In-place updates to existing specifications and standards that we reference - Update to of JSON Schema Specification. From 3b1d2ebb7e7fd2896bcd0ef78eb264b5853f6fff Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 3 Aug 2025 21:39:49 +0100 Subject: [PATCH 12/28] Catch up on the added features --- draft-release-notes.md | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 1bcd23a051..2dce1961b3 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -16,6 +16,15 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. +### Document identity and URL resolution + +- Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. + If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI. +- Other URL/URI handling does not change between 3.1 and 3.2 (but bears a recap in case you're wondering how it all goes together): + - Other URLs, such as to external documentation or a license, are resolved against the base URI. + - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. + - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI. + ### Updated security schemes - Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. @@ -27,7 +36,7 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Clarify that server URLs should not include fragment or query. - Support new `name` field alongside `description`, `url` and `variables`. -- Formal path templating support for variable substitution in server urls. +- Formal path templating support for variable substitution in server urls, alongside guidance that each variable can only be used once in a URL. ### Better polymorphic support @@ -37,10 +46,6 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. - Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. -### Reference resolution - -Additional top-level `$self` to be used as a base URI for resolving references in the OpenAPI description. If not present, the existing/earlier behaviour of using the retrieval URL as a base applies. - ### Path templating **ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. @@ -52,12 +57,12 @@ Additional top-level `$self` to be used as a base URI for resolving references i - `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). - The `xml` keyword can be used in any Schema Object. - XML namespaces can be IRIs (rather than URIs). -- Explanation and example on how to handle `null` in XML. +- Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. - Clarify that the root schema of an XML object should use the component name. ### Support for sequential media types -- Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `application/jsonl`, `application/json-seq` and others for sequential data. +- Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - Use `itemSchema` in a mediatype entry to describe each item. - Related: a new media types registry is published to give more context for each of the media types. @@ -69,6 +74,19 @@ Additional top-level `$self` to be used as a base URI for resolving references i - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. - `allowReserved` field is now permitted on headers and on parameters with any value of `in`. - Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. +- The `examples` (and older `example`) field is now supported with `content`. + +### Show examples in both structure and serialized forms + +- The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. +- `dataValue` describes the example in structured format. +- `serializedValue` shows how the example will be formatted when it is sent/received by the API. +- The existing `value` field can still be used, which means that you can safely upgrade to 3.2 and then revisit these fields and update them to use either `dataValue` or `serializedValue` as appropriate. + Use the new fields for examples you add after upgrading to 3.2. +- The existing `externalValue` field can still be used to give a reference to an example, but this is now clearly documented as being a serialized value. +- There are lots of examples of the examples (ha!) and clear documentation of how the fields can be combined. +- Summary of what to do: use `examples` over `example`, and use `dataValue` to show a clear, structured example of the data. + If your use case could benefit from an example of how the data will look when it's transmitted, use `serializedValue` as well. ### Flexible response metadata fields @@ -78,7 +96,9 @@ Additional top-level `$self` to be used as a base URI for resolving references i ### Minor edits that are worth a mention - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. -- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case +- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. +- A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects. + ### In-place updates to existing specifications and standards that we reference - Update to of JSON Schema Specification. @@ -89,10 +109,12 @@ Additional top-level `$self` to be used as a base URI for resolving references i ### Editorial changes - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. -- Clarification that Example Objects can be used in Header Objects. - Better explanation and examples for using Encoding. - Clarify that Request Body Objects need to specify at least one media type to be meaningful. - How to more clearly indicate that responses will not have a body. +- Explanation and examples of headers including `Link` and `Set-Cookie`. +- No change but extensive additional notes on parsing and serializing JSON and non-JSON data formats. + Particularly if you are buildling OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases. ## 3.1 Updates From ffb4bbbd21209803d632fcd1d95c78711d9bd5f5 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 3 Aug 2025 22:24:24 +0100 Subject: [PATCH 13/28] Refactor into sections --- draft-release-notes.md | 109 ++++++++++++++++++++++++----------------- 1 file changed, 63 insertions(+), 46 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 2dce1961b3..f9c76b1eb5 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -4,19 +4,25 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu ## 3.2 Updates -### Support additional HTTP methods +All the changes in the OpenAPI 3.2 release. -- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. -- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head`. +### Headline features + +A summary of the biggest changes. -### Nested, multipurpose tags +#### Nested, multipurpose tags - New `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. - `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy. - `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. -### Document identity and URL resolution +#### Support additional HTTP methods + +- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. +- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head`. + +#### Document identity and URL resolution - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI. @@ -25,32 +31,31 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI. -### Updated security schemes +### Data modeling and representation -- Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. -- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata. -- Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). -- Ability to reference a security scheme by URI rather than needing it declared in components. +OpenAPI specification v3.2 brings consistent, modular, and extensible media type and parameter support, while also expanding the set of media types supported in response to both emerging and legacy use cases. In addition, the ambiguity regarding how to present examples in a variety of complex scenarios is reduced. -### Servers +#### Support for sequential media types -- Clarify that server URLs should not include fragment or query. -- Support new `name` field alongside `description`, `url` and `variables`. -- Formal path templating support for variable substitution in server urls, alongside guidance that each variable can only be used once in a URL. +- Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. +- Responses can be a repeating data structure, and are treated as if they are an array of schema objects. +- Use `itemSchema` in a mediatype entry to describe each item. +- Related: a new media types registry is published to give more context for each of the media types. +- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads. -### Better polymorphic support +#### Parameter and header changes -- The discriminator `propertyName` can now be an optional field. -- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. -- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. -- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. -- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. +- Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. +- Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. +- `allowReserved` field is now permitted on headers and on parameters with any value of `in`. +- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. +- The `examples` (and older `example`) field is now supported with `content`. -### Path templating +#### Multipart media types -**ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. +**TODO** this section with the additional items fields and examples. -### Improvements for APIs using XML as a content format +#### Improvements for APIs using XML as a content format - New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. - `attribute: true` deprecated in favor of `nodeType: attribute`. @@ -60,23 +65,7 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. - Clarify that the root schema of an XML object should use the component name. -### Support for sequential media types - -- Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. -- Responses can be a repeating data structure, and are treated as if they are an array of schema objects. -- Use `itemSchema` in a mediatype entry to describe each item. -- Related: a new media types registry is published to give more context for each of the media types. -- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads. - -### Parameter and header changes - -- Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. -- Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. -- `allowReserved` field is now permitted on headers and on parameters with any value of `in`. -- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. -- The `examples` (and older `example`) field is now supported with `content`. - -### Show examples in both structure and serialized forms +#### Show examples in both structure and serialized forms - The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. - `dataValue` describes the example in structured format. @@ -88,25 +77,54 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Summary of what to do: use `examples` over `example`, and use `dataValue` to show a clear, structured example of the data. If your use case could benefit from an example of how the data will look when it's transmitted, use `serializedValue` as well. -### Flexible response metadata fields +### Additional features + +That's not all! Here are the rest of the changes for this release. + +#### Updated security schemes + +- Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. +- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata. +- Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). +- Ability to reference a security scheme by URI rather than needing it declared in components. + +#### Servers + +- Clarify that server URLs should not include fragment or query. +- Support new `name` field alongside `description`, `url` and `variables`. +- Formal path templating support for variable substitution in server urls, alongside guidance that each variable can only be used once in a URL. + +#### Better polymorphic support + +- The discriminator `propertyName` can now be an optional field. +- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. +- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. +- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. +- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. + +#### Path templating + +**ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. + +#### Flexible response metadata fields - `description` field for responses are now optional (they used to be required but they could be empty). - Additional `summary` field for responses, useful when displaying responses in a list context. -### Minor edits that are worth a mention +#### Minor edits that are worth a mention - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. - Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. - A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects. -### In-place updates to existing specifications and standards that we reference +#### In-place updates to existing specifications and standards that we reference - Update to of JSON Schema Specification. - Update to of JSON Schema Validation Specification. - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. -### Editorial changes +#### Editorial changes - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. - Better explanation and examples for using Encoding. @@ -120,11 +138,10 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu Version 3.1.2 has no material changes but does contain editorial fixes. -- Clarification that Example Objects can be used in Header Objects. - Better explanation and examples for using Encoding. - Clarify that Request Body Objects need to specify at least one media type to be meaningful - How to more clearly indicate that no response will have a body - How to handle `null` in XML as an advisory note; since the functionality cannot be changed it is implementation-defined for 3.1 tooling. - Clarify that the root schema of an XML object should use the component name. - + From dcace33073e739a422b8dd7b88211b42f41efa5a Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 12 Aug 2025 21:28:27 +0100 Subject: [PATCH 14/28] Add some examples for the smaller features, fix markdown --- draft-release-notes.md | 98 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 86 insertions(+), 12 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index f9c76b1eb5..d46969d755 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -27,9 +27,9 @@ A summary of the biggest changes. - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI. - Other URL/URI handling does not change between 3.1 and 3.2 (but bears a recap in case you're wondering how it all goes together): - - Other URLs, such as to external documentation or a license, are resolved against the base URI. - - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. - - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI. + - Other URLs, such as to external documentation or a license, are resolved against the base URI. + - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. + - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI. ### Data modeling and representation @@ -79,39 +79,113 @@ OpenAPI specification v3.2 brings consistent, modular, and extensible media type ### Additional features -That's not all! Here are the rest of the changes for this release. +That's not all! Here are the rest of the changes for this release, each one is small but mighty! #### Updated security schemes -- Support for OAuth2 Device Authorization flow with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. -- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata. +- Support for [OAuth2 Device Authorization flow](https://datatracker.ietf.org/doc/html/rfc8628) with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. This flow is designed for devices that have limited inputs such as TVs, printers, and kiosks. +- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata, as described by the [OAuth2 Server Metadata Standard](https://datatracker.ietf.org/doc/html/rfc8414). - Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). - Ability to reference a security scheme by URI rather than needing it declared in components. +```yaml +components: + securitySchemes: + cakeStoreOAuth: + type: oauth2 + description: OAuth2 security for Cake Store API + flows: + deviceAuthorization: + deviceAuthorizationUrl: https://auth.cakestore.com/oauth/device/authorize + tokenUrl: https://auth.cakestore.com/oauth/token + scopes: + read:cakes: Read access to cake catalog + write:orders: Place cake orders from your device + device:monitor: Monitor cake order status + +``` + #### Servers - Clarify that server URLs should not include fragment or query. - Support new `name` field alongside `description`, `url` and `variables`. -- Formal path templating support for variable substitution in server urls, alongside guidance that each variable can only be used once in a URL. +- Formal ABNF syntax for the allowed variable substitution in server urls, alongside guidance that each variable can only be used once in a URL. + +Use the name field to refer to servers easily: + +```yaml +servers: + - name: Production + url: https://api.cakestore.com/v1 + description: Production server for live cake orders + - name: Staging + url: https://staging-api.cakestore.com/v1 + description: Staging environment for testing new cake recipes and features + - name: Local + url: http://localhost:3000/v1 + description: Local development server running on your machine +``` #### Better polymorphic support +Discriminator is a great way to match the correct schema to a payload. This release gives more robustness by adding support for a default type so that unknown objects can be handled safely. + - The discriminator `propertyName` can now be an optional field. -- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. +- New field `defaultMapping` to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. - No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. - No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. - Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. -#### Path templating - -**ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object. +Define the `mapping` and `discriminator` as before. The new field `defaultMapping` will be used if either the discriminator doesn't have a `propertyName` or when there is an object that doesn't match a `mapping` entry. + +```yaml + schemas: + Cake: + type: object + discriminator: + propertyName: cakeType + defaultMapping: sponge + mapping: + sponge: '#/components/schemas/SpongeCake' + chocolate: '#/components/schemas/ChocolateCake' + fruit: '#/components/schemas/FruitCake' + properties: + cakeType: + type: string + enum: [sponge, chocolate, fruit] + name: + type: string +``` + +#### Templates with formal syntax + +The specification now includes **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in the Links object. +This sounds terribly formal but it means that there is a clear syntax for what is supported in each of those locations, that existing tooling can understand. + +Next time you're wondering if you can do `/api/v{version}/users/{user-id}` in a path template, it'll be easy to check (spoiler: yes you can). #### Flexible response metadata fields - `description` field for responses are now optional (they used to be required but they could be empty). - Additional `summary` field for responses, useful when displaying responses in a list context. -#### Minor edits that are worth a mention +```yaml + /cakes: + get: + summary: List cakes + responses: + '200': + summary: Cake list + description: A list of cakes (this field is no longer required) + content: + application/json: + schema: + type: array + items: + type: string +``` + +#### Minor updates that are worth a mention - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. - Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. From 947723e5fea06cee0e9141f2a55e85de231f0882 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 12 Aug 2025 21:31:55 +0100 Subject: [PATCH 15/28] Better opening section for security schemes --- draft-release-notes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/draft-release-notes.md b/draft-release-notes.md index d46969d755..fa6ed90969 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -83,6 +83,8 @@ That's not all! Here are the rest of the changes for this release, each one is s #### Updated security schemes +Since the OpenAPI 3.1 release, there have been plenty of good innovations in API security. OpenAPI 3.2 brings support for some of the key areas so you can keep pace with best practice on security topics. + - Support for [OAuth2 Device Authorization flow](https://datatracker.ietf.org/doc/html/rfc8628) with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. This flow is designed for devices that have limited inputs such as TVs, printers, and kiosks. - Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata, as described by the [OAuth2 Server Metadata Standard](https://datatracker.ietf.org/doc/html/rfc8414). - Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). From b69d9df3e4d83bd708c0c2d4c32c7f5446e08b6b Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 17 Aug 2025 16:09:49 +0100 Subject: [PATCH 16/28] Update draft-release-notes.md Co-authored-by: Ralf Handl --- draft-release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index fa6ed90969..102d45ebb8 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -65,7 +65,7 @@ OpenAPI specification v3.2 brings consistent, modular, and extensible media type - Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. - Clarify that the root schema of an XML object should use the component name. -#### Show examples in both structure and serialized forms +#### Show examples in both structured and serialized forms - The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. - `dataValue` describes the example in structured format. From 5f2ccbb18cb711497ddb7c0561698818830b6323 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 17 Aug 2025 16:11:50 +0100 Subject: [PATCH 17/28] Update draft-release-notes.md Co-authored-by: Ralf Handl --- draft-release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 102d45ebb8..0b041666cc 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -208,7 +208,7 @@ Next time you're wondering if you can do `/api/v{version}/users/{user-id}` in a - How to more clearly indicate that responses will not have a body. - Explanation and examples of headers including `Link` and `Set-Cookie`. - No change but extensive additional notes on parsing and serializing JSON and non-JSON data formats. - Particularly if you are buildling OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases. + Particularly if you are building OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases. ## 3.1 Updates From a82974409eebcc2be5cc7399d4b29584ba1bd308 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 17 Aug 2025 19:39:23 +0100 Subject: [PATCH 18/28] Add multipart media types section, tidy up from other feedback, add recent minor additions --- draft-release-notes.md | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 0b041666cc..8b1171449d 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -12,9 +12,12 @@ A summary of the biggest changes. #### Nested, multipurpose tags -- New `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. +Tags get an upgrade, with some new fields to make them more useful and reflect some of the features that need extensions to achieve today: + +- `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead. - `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy. -- `kind` to allow multiple categories of tag. The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). +- `kind` field to allow a tag to be classified into a category such as navigation, or audience. + The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. #### Support additional HTTP methods @@ -35,6 +38,8 @@ A summary of the biggest changes. OpenAPI specification v3.2 brings consistent, modular, and extensible media type and parameter support, while also expanding the set of media types supported in response to both emerging and legacy use cases. In addition, the ambiguity regarding how to present examples in a variety of complex scenarios is reduced. +There is also a new Media Types Registry, to provide further resources for working with different media types. + #### Support for sequential media types - Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. @@ -53,7 +58,15 @@ OpenAPI specification v3.2 brings consistent, modular, and extensible media type #### Multipart media types -**TODO** this section with the additional items fields and examples. +Multipart media types are much better supported in OpenAPI 3.2. + +- New `itemSchema` field, for the schema that describes each of the items in a sequential media type. + These sequential types may not be received or parsed in one go, so the `itemSchema` field supports ongoing parsing. +- New fields `prefixEncoding` and `itemEncoding` can be used instead of `encoding` for multipart media types. + - Use `prefixEncoding` with an array of positional encoding information where the position of each item in the content is known. + - The `itemEncoding` is a single encoding entry that is used for information about multiple items. +- The specification also contains examples of sequential JSON and Server-Sent events that show these fields in use. +- Nested content types are supported to at least one level of nesting. #### Improvements for APIs using XML as a content format @@ -65,7 +78,7 @@ OpenAPI specification v3.2 brings consistent, modular, and extensible media type - Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. - Clarify that the root schema of an XML object should use the component name. -#### Show examples in both structured and serialized forms +#### Describe examples in both structured and serialized forms - The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. - `dataValue` describes the example in structured format. @@ -189,7 +202,6 @@ Next time you're wondering if you can do `/api/v{version}/users/{user-id}` in a #### Minor updates that are worth a mention -- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. - Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. - A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects. @@ -203,20 +215,24 @@ Next time you're wondering if you can do `/api/v{version}/users/{user-id}` in a #### Editorial changes - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. -- Better explanation and examples for using Encoding. +- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. +- Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. - Clarify that Request Body Objects need to specify at least one media type to be meaningful. - How to more clearly indicate that responses will not have a body. - Explanation and examples of headers including `Link` and `Set-Cookie`. -- No change but extensive additional notes on parsing and serializing JSON and non-JSON data formats. - Particularly if you are building OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases. +- Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. +- Extensive additional notes on parsing and serializing JSON and non-JSON data formats. + +Particularly if you are building OpenAPI tooling, these sections give much better guidance on some of those tricky edge cases. ## 3.1 Updates Version 3.1.2 has no material changes but does contain editorial fixes. -- Better explanation and examples for using Encoding. -- Clarify that Request Body Objects need to specify at least one media type to be meaningful -- How to more clearly indicate that no response will have a body +- Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. +- Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. +- Clarify that Request Body Objects need to specify at least one media type to be meaningful. +- How to more clearly indicate that no response will have a body. - How to handle `null` in XML as an advisory note; since the functionality cannot be changed it is implementation-defined for 3.1 tooling. - Clarify that the root schema of an XML object should use the component name. From e4ca9a6511b6cb91019b70131f11f787f7edf4f2 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 17 Aug 2025 19:41:01 +0100 Subject: [PATCH 19/28] Correct indentation of sub-bullets --- draft-release-notes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 8b1171449d..bb42712705 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -63,8 +63,8 @@ Multipart media types are much better supported in OpenAPI 3.2. - New `itemSchema` field, for the schema that describes each of the items in a sequential media type. These sequential types may not be received or parsed in one go, so the `itemSchema` field supports ongoing parsing. - New fields `prefixEncoding` and `itemEncoding` can be used instead of `encoding` for multipart media types. - - Use `prefixEncoding` with an array of positional encoding information where the position of each item in the content is known. - - The `itemEncoding` is a single encoding entry that is used for information about multiple items. + - Use `prefixEncoding` with an array of positional encoding information where the position of each item in the content is known. + - The `itemEncoding` is a single encoding entry that is used for information about multiple items. - The specification also contains examples of sequential JSON and Server-Sent events that show these fields in use. - Nested content types are supported to at least one level of nesting. From 9a9c49850c2ea30fc00837230a97ce7b9cb25a0e Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 17 Aug 2025 20:24:59 +0100 Subject: [PATCH 20/28] Add some more examples --- draft-release-notes.md | 109 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/draft-release-notes.md b/draft-release-notes.md index bb42712705..cfa5c87c26 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -20,11 +20,109 @@ Tags get an upgrade, with some new fields to make them more useful and reflect s The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. +An example of nested tags using the new fields might be as follows: + +```yaml +tags: + - name: products + summary: Products + description: All cake and bakery product operations + kind: nav + + - name: cakes + summary: Cakes and Treats + description: Cake catalog, ordering, and customization + parent: products + kind: nav + + - name: extra + summary: Accessories + description: Candles, decorations, and cake serving supplies + parent: products + kind: nav + + - name: seasonal + summary: Seasonal + description: Limited-time seasonal offerings + kind: badge + externalDocs: + description: Seasonal menu planning guide + url: https://docs.cakestore.com/seasonal-planning +``` + #### Support additional HTTP methods - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. + Query is a new method in the HTTP standard, designed to allow complex filtering query data to be sent in the body of a request when it doesn't fit in the query string. - Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head`. +The following example describes both `query` and `link` methods for the `cakes/` endpoint: + +```yaml +paths: + /cakes: + get: + summary: List available cakes + responses: + '200': + description: List of cakes + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Cake' + + query: + summary: Advanced cake search with complex filtering + description: Search cakes using advanced query syntax in request body + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + filter: + type: string + example: "flavor:chocolate AND price:<20" + sort: + type: array + items: + type: string + example: ["price:asc", "rating:desc"] + responses: + '200': + description: Search results + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Cake' + + additionalOperations: + LINK: + summary: Link related cake products + description: Create associations between cakes and accessories + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + targetResource: + type: string + example: "/accessories/candles/123" + relationship: + type: string + example: "recommended-with" + responses: + '204': + description: Link created successfully +``` + #### Document identity and URL resolution - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. @@ -34,6 +132,17 @@ Tags get an upgrade, with some new fields to make them more useful and reflect s - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI. +The following example shows the new `$self` field in use: + +```yaml +openapi: 3.2.0 +$self: https://cake-api.example.com/openapi.yaml +info: + title: Cake Store API + version: 1.0.3 + description: API for managing cake orders and inventory +``` + ### Data modeling and representation OpenAPI specification v3.2 brings consistent, modular, and extensible media type and parameter support, while also expanding the set of media types supported in response to both emerging and legacy use cases. In addition, the ambiguity regarding how to present examples in a variety of complex scenarios is reduced. From 403a01069ff59f0b50dc60c7606e716461a3fb28 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sat, 23 Aug 2025 12:14:02 +0100 Subject: [PATCH 21/28] Update draft-release-notes.md Co-authored-by: Ralf Handl --- draft-release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index cfa5c87c26..cf4c7d1ad9 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -54,7 +54,7 @@ tags: - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. Query is a new method in the HTTP standard, designed to allow complex filtering query data to be sent in the body of a request when it doesn't fit in the query string. -- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. do NOT add HEAD under this, use the existing sibling `head`. +- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. `LINK`. Do NOT add `HEAD` under this, use the existing sibling `head`. The following example describes both `query` and `link` methods for the `cakes/` endpoint: From e8cc875e16bce78119ce2641c3c57afd4622e019 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 25 Aug 2025 10:23:46 +0100 Subject: [PATCH 22/28] Add style: cookie and other recent changes --- draft-release-notes.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index cf4c7d1ad9..22d4ad160f 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -161,10 +161,15 @@ There is also a new Media Types Registry, to provide further resources for worki - Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. -- `allowReserved` field is now permitted on headers and on parameters with any value of `in`. +- `allowReserved` field is now permitted on headers and on parameters with any value of `in`, and applies where the combination of `in` and `style` automatically percent-encode the value. - Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. - The `examples` (and older `example`) field is now supported with `content`. +### Specific `style` option for cookies + +- Additional `style` option `cookie` for content in a cookie, which uses semicolon as a separator and does not encode data values. + The `form` style is a close fit, but you may wish to switch to `cookie` for more correct description. + #### Multipart media types Multipart media types are much better supported in OpenAPI 3.2. @@ -336,8 +341,9 @@ Particularly if you are building OpenAPI tooling, these sections give much bette ## 3.1 Updates -Version 3.1.2 has no material changes but does contain editorial fixes. +Version 3.1.2 has no material changes but does contain editorial fixes, additional examples, and clarifications. +- Clarify that `$ref` in a Schema Object is a JSONSchema `$ref` keyword. - Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. - Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. - Clarify that Request Body Objects need to specify at least one media type to be meaningful. From ca5f9f28f8ed1df41a0e0745a0265d7f9cbcc49d Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 31 Aug 2025 17:05:18 +0100 Subject: [PATCH 23/28] Add a much slimmer list of changes for the release notes --- draft-release-notes.md | 6 +- summary-release-notes.md | 133 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+), 3 deletions(-) create mode 100644 summary-release-notes.md diff --git a/draft-release-notes.md b/draft-release-notes.md index 22d4ad160f..a5f3253688 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -10,7 +10,7 @@ All the changes in the OpenAPI 3.2 release. A summary of the biggest changes. -#### Nested, multipurpose tags +#### Tags: nested, multipurpose, and not just for documentation Tags get an upgrade, with some new fields to make them more useful and reflect some of the features that need extensions to achieve today: @@ -165,7 +165,7 @@ There is also a new Media Types Registry, to provide further resources for worki - Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. - The `examples` (and older `example`) field is now supported with `content`. -### Specific `style` option for cookies +#### Specific `style` option for cookies - Additional `style` option `cookie` for content in a cookie, which uses semicolon as a separator and does not encode data values. The `form` style is a close fit, but you may wish to switch to `cookie` for more correct description. @@ -185,7 +185,7 @@ Multipart media types are much better supported in OpenAPI 3.2. #### Improvements for APIs using XML as a content format - New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. -- `attribute: true` deprecated in favor of `nodeType: attribute`. +- `attribute: true` is now deprecated in favor of `nodeType: attribute`. - `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). - The `xml` keyword can be used in any Schema Object. - XML namespaces can be IRIs (rather than URIs). diff --git a/summary-release-notes.md b/summary-release-notes.md new file mode 100644 index 0000000000..7c7f9d3375 --- /dev/null +++ b/summary-release-notes.md @@ -0,0 +1,133 @@ +# [DRAFT]: Release Notes + +What's coming up? Look at `src/oas.md` on the relevant development branch for full details. + +## 3.2 Updates + +### Headline features + +- Multipurpose tags, with nesting + + - `summary` field to allow short descriptions, used when displaying lists of tags. + - `parent` field to point to the tag that this tag is nested under. + - `kind` field to allow a tag to be classified into a category such as navigation, or audience. + The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output). + - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. + +- Support for additional HTTP methods + + - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. + - Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. `LINK`. Do NOT add `HEAD` under this, use the existing sibling `head`. + +- Document identity and URL resolution + + - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. + - More explanation and examples regarding URL resolution. + +### Data modeling and representation + +- Streaming support: sequential media types including SSE + + - Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. + - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. + - Use `itemSchema` in a mediatype entry to describe each item. + - A media types registry is published to give more context for each of the media types. + +- Parameter and header changes + + - Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. + - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. + - `allowReserved` field is now permitted on headers and on parameters with any value of `in`, and applies where the combination of `in` and `style` automatically percent-encode the value. + +- New `style` option for cookies + + - Additional `style` option `cookie` for content in a cookie, which uses semicolon as a separator and does not encode data values. + +- Additions to support multipart media types + + - New `itemSchema` field, for the schema that describes each of the items in a sequential media type. + - New fields `prefixEncoding` and `itemEncoding` can be used instead of `encoding` for multipart media types. + - The specification also contains examples of sequential JSON and Server-Sent events that show these fields in use. + +- Improvements for APIs using XML as a content format + + - New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. + - `attribute: true` is now deprecated in favor of `nodeType: attribute`. + - `wrapped: true` is now deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). + - The `xml` keyword can be used in any Schema Object. + - XML namespaces can be IRIs (rather than URIs). + - Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. + - Clarify that the root schema of an XML object should use the component name. + +- Examples as either structured or serialised values + + - The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. + - `dataValue` describes the example in structured format. + - `serializedValue` shows how the example will be formatted when it is sent/received by the API. + - The existing `externalValue` field can still be used to give a reference to an example, but this is now clearly documented as being a serialized value. + +### Additional features + +- Updated security schemes + + - Support for [OAuth2 Device Authorization flow](https://datatracker.ietf.org/doc/html/rfc8628) with additional `deviceAuthorization` field in the `flows` object and for the individual flow, a new field `deviceAuthorizationUrl` alongside `tokenUrl`. + - Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata, as described by the [OAuth2 Server Metadata Standard](https://datatracker.ietf.org/doc/html/rfc8414). + - Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). + - Ability to reference a security scheme by URI rather than declaring it in components. + +- Improvements to the Servers object + + - Clarify that server URLs should not include fragment or query. + - Support new `name` field alongside `description`, `url` and `variables`. + - Formal ABNF syntax for the allowed variable substitution in server urls, alongside guidance that each variable can only be used once in a URL. + +- Better polymorphic support + + - The discriminator `propertyName` can now be an optional field. + - New field `defaultMapping` to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. + +- Templates with formal syntax + + - The specification now includes **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in the Links object. + +- Flexible metadata fields in the Response object + + - `description` field for responses are now optional. + - Additional `summary` field for responses. + +- Additional updates + + - Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. + - A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects. + +- Updates to referenced standards + + - Update to of JSON Schema Specification. + - Update to of JSON Schema Validation Specification. + - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. + - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. + +- Editorial changes + + - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. + - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. + - Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. + - Clarify that Request Body Objects need to specify at least one media type to be meaningful. + - How to more clearly indicate that responses will not have a body. + - Explanation and examples of headers including `Link` and `Set-Cookie`. + - Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. + - Extensive additional notes on parsing and serializing JSON and non-JSON data formats. + +## 3.1 Updates + +Version 3.1.2 has no material changes but does contain editorial fixes, additional examples, and clarifications. + +- Clarify that `$ref` in a Schema Object is a JSONSchema `$ref` keyword. +- Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. +- Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. +- Clarify that Request Body Objects need to specify at least one media type to be meaningful. +- How to more clearly indicate that no response will have a body. +- How to handle `null` in XML as an advisory note; since the functionality cannot be changed it is implementation-defined for 3.1 tooling. +- Clarify that the root schema of an XML object should use the component name. + + From a1e8818857d027f22b9e034e4a76622269a6adcb Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 7 Sep 2025 18:48:45 +0100 Subject: [PATCH 24/28] Apply suggestions from code review Co-authored-by: Ralf Handl --- draft-release-notes.md | 4 ++-- summary-release-notes.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index a5f3253688..407d67aa40 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -162,7 +162,7 @@ There is also a new Media Types Registry, to provide further resources for worki - Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. - `allowReserved` field is now permitted on headers and on parameters with any value of `in`, and applies where the combination of `in` and `style` automatically percent-encode the value. -- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context. +- Remove incorrect mention of Reference Object in the header `schema` field. The JSON Schema `$ref` would be the correct thing to use in this context. - The `examples` (and older `example`) field is now supported with `content`. #### Specific `style` option for cookies @@ -343,7 +343,7 @@ Particularly if you are building OpenAPI tooling, these sections give much bette Version 3.1.2 has no material changes but does contain editorial fixes, additional examples, and clarifications. -- Clarify that `$ref` in a Schema Object is a JSONSchema `$ref` keyword. +- Clarify that `$ref` in a Schema Object is a JSON Schema `$ref` keyword. - Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. - Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. - Clarify that Request Body Objects need to specify at least one media type to be meaningful. diff --git a/summary-release-notes.md b/summary-release-notes.md index 7c7f9d3375..0f309eadd7 100644 --- a/summary-release-notes.md +++ b/summary-release-notes.md @@ -29,7 +29,7 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Streaming support: sequential media types including SSE - Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. - - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. + - Responses can be a repeating data structure, and are treated as if they are an array of Schema Objects. - Use `itemSchema` in a mediatype entry to describe each item. - A media types registry is published to give more context for each of the media types. @@ -57,9 +57,9 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - The `xml` keyword can be used in any Schema Object. - XML namespaces can be IRIs (rather than URIs). - Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. - - Clarify that the root schema of an XML object should use the component name. + - Clarify that the root schema of an XML Object should use the component name. -- Examples as either structured or serialised values +- Examples as either structured or serialized values - The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. - `dataValue` describes the example in structured format. @@ -75,7 +75,7 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). - Ability to reference a security scheme by URI rather than declaring it in components. -- Improvements to the Servers object +- Improvements to the Server Object - Clarify that server URLs should not include fragment or query. - Support new `name` field alongside `description`, `url` and `variables`. @@ -88,11 +88,11 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Templates with formal syntax - - The specification now includes **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in the Links object. + - The specification now includes **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in the Link Object. -- Flexible metadata fields in the Response object +- Flexible metadata fields in the Response Object - - `description` field for responses are now optional. + - `description` field for responses is now optional. - Additional `summary` field for responses. - Additional updates @@ -122,7 +122,7 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu Version 3.1.2 has no material changes but does contain editorial fixes, additional examples, and clarifications. -- Clarify that `$ref` in a Schema Object is a JSONSchema `$ref` keyword. +- Clarify that `$ref` in a Schema Object is a JSON Schema `$ref` keyword. - Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. - Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. - Clarify that Request Body Objects need to specify at least one media type to be meaningful. From 556455024426850a100f8e06042dccdf57582942 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 9 Sep 2025 08:04:59 +0100 Subject: [PATCH 25/28] Apply suggestions from code review Co-authored-by: Henry Andrews Co-authored-by: Karen Etheridge --- draft-release-notes.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 407d67aa40..20417d1f36 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -53,10 +53,10 @@ tags: #### Support additional HTTP methods - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. - Query is a new method in the HTTP standard, designed to allow complex filtering query data to be sent in the body of a request when it doesn't fit in the query string. + QUERY is a [draft standard](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) new HTTP method nearing final publication, which is designed to allow complex filtering query data to be sent in the body of a request when it doesn't fit in the query string. - Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. `LINK`. Do NOT add `HEAD` under this, use the existing sibling `head`. -The following example describes both `query` and `link` methods for the `cakes/` endpoint: +The following example describes both QUERY and LINK methods for the `cakes/` endpoint: ```yaml paths: @@ -128,7 +128,7 @@ paths: - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI. - Other URL/URI handling does not change between 3.1 and 3.2 (but bears a recap in case you're wondering how it all goes together): - - Other URLs, such as to external documentation or a license, are resolved against the base URI. + - Other URIs, such as to external documentation or a license, are resolved against the base URI. - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI. @@ -154,26 +154,27 @@ There is also a new Media Types Registry, to provide further resources for worki - Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. - Use `itemSchema` in a mediatype entry to describe each item. -- Related: a new media types registry is published to give more context for each of the media types. -- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads. +- Related: a new media types registry is published to give more context for each of the media types and allow registration of future media type support outside of the OAS publication schedule. +- Also a "Complete vs Streaming Content" section for guidance on streaming payloads. #### Parameter and header changes -- Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field. +- Additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` location. - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. -- `allowReserved` field is now permitted on headers and on parameters with any value of `in`, and applies where the combination of `in` and `style` automatically percent-encode the value. -- Remove incorrect mention of Reference Object in the header `schema` field. The JSON Schema `$ref` would be the correct thing to use in this context. +- `allowReserved` now applies anywhere the combination of `in` and `style` automatically percent-encode the value. +- Remove incorrect mention of Reference Object in the header `schema` field, which is redundant with the `$ref` coming from JSON Schema itself. - The `examples` (and older `example`) field is now supported with `content`. #### Specific `style` option for cookies - Additional `style` option `cookie` for content in a cookie, which uses semicolon as a separator and does not encode data values. - The `form` style is a close fit, but you may wish to switch to `cookie` for more correct description. + The `form` style is a close fit, but you may wish to switch to `cookie` for a more correct description. #### Multipart media types Multipart media types are much better supported in OpenAPI 3.2. +- `multipart/mixed`, on which most other `multipart` formats are based, is now supported - New `itemSchema` field, for the schema that describes each of the items in a sequential media type. These sequential types may not be received or parsed in one go, so the `itemSchema` field supports ongoing parsing. - New fields `prefixEncoding` and `itemEncoding` can be used instead of `encoding` for multipart media types. @@ -184,9 +185,9 @@ Multipart media types are much better supported in OpenAPI 3.2. #### Improvements for APIs using XML as a content format -- New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. +- New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`, defaulting to `element` for most data types, or `none` for arrays. - `attribute: true` is now deprecated in favor of `nodeType: attribute`. -- `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). +- `wrapped: true` for arrays deprecated in favor of `nodeType: element` (set explicitly to override the default `nodeType: none` for arrays) - The `xml` keyword can be used in any Schema Object. - XML namespaces can be IRIs (rather than URIs). - Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. @@ -324,8 +325,8 @@ Next time you're wondering if you can do `/api/v{version}/users/{user-id}` in a - Update to of JSON Schema Specification. - Update to of JSON Schema Validation Specification. - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. +- Use [RFC9512](https://www.rfc-editor.org/rfc/rfc9512.html) for YAML, particularly for defining JSON-compatible YAML. - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. - #### Editorial changes - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. From 4c02500f0e3aa708441b2bf7edb4daa89a6ca1ee Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 14 Sep 2025 15:19:55 +0100 Subject: [PATCH 26/28] Apply suggestions from code review Co-authored-by: Henry Andrews --- draft-release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 20417d1f36..1c9c5797cf 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -54,7 +54,7 @@ tags: - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. QUERY is a [draft standard](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) new HTTP method nearing final publication, which is designed to allow complex filtering query data to be sent in the body of a request when it doesn't fit in the query string. -- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. `LINK`. Do NOT add `HEAD` under this, use the existing sibling `head`. +- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field. The following example describes both QUERY and LINK methods for the `cakes/` endpoint: From de6cf5f9c7f813ec40aa02d88c2cc77dd1cd2750 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 14 Sep 2025 15:50:24 +0100 Subject: [PATCH 27/28] More updates from feedback, thanks everyone --- draft-release-notes.md | 18 ++++++++++-------- summary-release-notes.md | 1 - 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index 1c9c5797cf..fe32a54af7 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -126,11 +126,11 @@ paths: #### Document identity and URL resolution - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. - If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI. + If no `$self` field is defined, then the base URI behaves as it did in previous versions of OpenAPI - in most cases the retrieval URL. - Other URL/URI handling does not change between 3.1 and 3.2 (but bears a recap in case you're wondering how it all goes together): - Other URIs, such as to external documentation or a license, are resolved against the base URI. - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. - - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI. + - API paths are appended to the URL in the Server Object, which itself might be relative and resolved against the retrieval URI of the document. The following example shows the new `$self` field in use: @@ -153,7 +153,7 @@ There is also a new Media Types Registry, to provide further resources for worki - Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data. - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. -- Use `itemSchema` in a mediatype entry to describe each item. +- Use `itemSchema` in a media type entry to describe each item. - Related: a new media types registry is published to give more context for each of the media types and allow registration of future media type support outside of the OAS publication schedule. - Also a "Complete vs Streaming Content" section for guidance on streaming payloads. @@ -196,11 +196,11 @@ Multipart media types are much better supported in OpenAPI 3.2. #### Describe examples in both structured and serialized forms - The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. -- `dataValue` describes the example in structured format. -- `serializedValue` shows how the example will be formatted when it is sent/received by the API. +- `dataValue` describes the example in structured format, suitable for evaluating with a schema. +- `serializedValue` shows how a UTF-8 compatible serialization of the example will be formatted when it is sent/received by the API. +- The existing `externalValue` field can still be used to give a reference to an example; this is the best way to include examples where the serialization is not UTF-8 compatible. - The existing `value` field can still be used, which means that you can safely upgrade to 3.2 and then revisit these fields and update them to use either `dataValue` or `serializedValue` as appropriate. Use the new fields for examples you add after upgrading to 3.2. -- The existing `externalValue` field can still be used to give a reference to an example, but this is now clearly documented as being a serialized value. - There are lots of examples of the examples (ha!) and clear documentation of how the fields can be combined. - Summary of what to do: use `examples` over `example`, and use `dataValue` to show a clear, structured example of the data. If your use case could benefit from an example of how the data will look when it's transmitted, use `serializedValue` as well. @@ -264,7 +264,6 @@ Discriminator is a great way to match the correct schema to a payload. This rele - New field `defaultMapping` to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. - No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected. - No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match. -- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. Define the `mapping` and `discriminator` as before. The new field `defaultMapping` will be used if either the discriminator doesn't have a `propertyName` or when there is an object that doesn't match a `mapping` entry. @@ -317,8 +316,8 @@ Next time you're wondering if you can do `/api/v{version}/users/{user-id}` in a #### Minor updates that are worth a mention -- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. - A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects. +- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`. #### In-place updates to existing specifications and standards that we reference @@ -327,8 +326,11 @@ Next time you're wondering if you can do `/api/v{version}/users/{user-id}` in a - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. - Use [RFC9512](https://www.rfc-editor.org/rfc/rfc9512.html) for YAML, particularly for defining JSON-compatible YAML. - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. + #### Editorial changes +- Re-organization of the top-level sections to group more content with the most relevant Objects and bring the start of the Objects and Fields (formerly Schema) section close to the top of the specification. +- Substantial streamlining and simplification of document parsing, relative URI-reference resolution, and implicit connection resolution, including examples of base URI determination - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. - Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. diff --git a/summary-release-notes.md b/summary-release-notes.md index 0f309eadd7..58a46c180b 100644 --- a/summary-release-notes.md +++ b/summary-release-notes.md @@ -97,7 +97,6 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu - Additional updates - - Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. - A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects. - Updates to referenced standards From 540c9bfe7869d0a60813e374b252059617e4d7e0 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 14 Sep 2025 15:56:33 +0100 Subject: [PATCH 28/28] Fix formatting --- draft-release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-release-notes.md b/draft-release-notes.md index fe32a54af7..b022a44d2a 100644 --- a/draft-release-notes.md +++ b/draft-release-notes.md @@ -130,7 +130,7 @@ paths: - Other URL/URI handling does not change between 3.1 and 3.2 (but bears a recap in case you're wondering how it all goes together): - Other URIs, such as to external documentation or a license, are resolved against the base URI. - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page. - - API paths are appended to the URL in the Server Object, which itself might be relative and resolved against the retrieval URI of the document. + - API paths are appended to the URL in the Server Object, which itself might be relative and resolved against the retrieval URI of the document The following example shows the new `$self` field in use: