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/10] 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/10] 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/10] 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/10] 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/10] 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/10] 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/10] 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/10] 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/10] 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/10] 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