|
| 1 | +# [DRAFT]: Release Notes |
| 2 | + |
| 3 | +What's coming up? Look at `src/oas.md` on the relevant development branch for full details. |
| 4 | + |
| 5 | +## 3.2 Updates |
| 6 | + |
| 7 | +### Headline features |
| 8 | + |
| 9 | +- Multipurpose tags, with nesting |
| 10 | + |
| 11 | + - `summary` field to allow short descriptions, used when displaying lists of tags. |
| 12 | + - `parent` field to point to the tag that this tag is nested under. |
| 13 | + - `kind` field to allow a tag to be classified into a category such as navigation, or audience. |
| 14 | + 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). |
| 15 | + - A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`. |
| 16 | + |
| 17 | +- Support for additional HTTP methods |
| 18 | + |
| 19 | + - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`. |
| 20 | + - 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`. |
| 21 | + |
| 22 | +- Document identity and URL resolution |
| 23 | + |
| 24 | + - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references. |
| 25 | + - More explanation and examples regarding URL resolution. |
| 26 | + |
| 27 | +### Data modeling and representation |
| 28 | + |
| 29 | +- Streaming support: sequential media types including SSE |
| 30 | + |
| 31 | + - 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. |
| 32 | + - Responses can be a repeating data structure, and are treated as if they are an array of schema objects. |
| 33 | + - Use `itemSchema` in a mediatype entry to describe each item. |
| 34 | + - A media types registry is published to give more context for each of the media types. |
| 35 | + |
| 36 | +- Parameter and header changes |
| 37 | + |
| 38 | + - 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. |
| 39 | + - Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values. |
| 40 | + - `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. |
| 41 | + |
| 42 | +- New `style` option for cookies |
| 43 | + |
| 44 | + - Additional `style` option `cookie` for content in a cookie, which uses semicolon as a separator and does not encode data values. |
| 45 | + |
| 46 | +- Additions to support multipart media types |
| 47 | + |
| 48 | + - New `itemSchema` field, for the schema that describes each of the items in a sequential media type. |
| 49 | + - New fields `prefixEncoding` and `itemEncoding` can be used instead of `encoding` for multipart media types. |
| 50 | + - The specification also contains examples of sequential JSON and Server-Sent events that show these fields in use. |
| 51 | + |
| 52 | +- Improvements for APIs using XML as a content format |
| 53 | + |
| 54 | + - New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`. |
| 55 | + - `attribute: true` is now deprecated in favor of `nodeType: attribute`. |
| 56 | + - `wrapped: true` is now deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility). |
| 57 | + - The `xml` keyword can be used in any Schema Object. |
| 58 | + - XML namespaces can be IRIs (rather than URIs). |
| 59 | + - Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements. |
| 60 | + - Clarify that the root schema of an XML object should use the component name. |
| 61 | + |
| 62 | +- Examples as either structured or serialised values |
| 63 | + |
| 64 | + - The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`. |
| 65 | + - `dataValue` describes the example in structured format. |
| 66 | + - `serializedValue` shows how the example will be formatted when it is sent/received by the API. |
| 67 | + - 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. |
| 68 | + |
| 69 | +### Additional features |
| 70 | + |
| 71 | +- Updated security schemes |
| 72 | + |
| 73 | + - 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`. |
| 74 | + - 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). |
| 75 | + - Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used). |
| 76 | + - Ability to reference a security scheme by URI rather than declaring it in components. |
| 77 | + |
| 78 | +- Improvements to the Servers object |
| 79 | + |
| 80 | + - Clarify that server URLs should not include fragment or query. |
| 81 | + - Support new `name` field alongside `description`, `url` and `variables`. |
| 82 | + - Formal ABNF syntax for the allowed variable substitution in server urls, alongside guidance that each variable can only be used once in a URL. |
| 83 | + |
| 84 | +- Better polymorphic support |
| 85 | + |
| 86 | + - The discriminator `propertyName` can now be an optional field. |
| 87 | + - New field `defaultMapping` to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. |
| 88 | + |
| 89 | +- Templates with formal syntax |
| 90 | + |
| 91 | + - The specification now includes **ABNF** (Augmented Backus–Naur Form) for path templating, server variables, and runtime expressions in the Links object. |
| 92 | + |
| 93 | +- Flexible metadata fields in the Response object |
| 94 | + |
| 95 | + - `description` field for responses are now optional. |
| 96 | + - Additional `summary` field for responses. |
| 97 | + |
| 98 | +- Additional updates |
| 99 | + |
| 100 | + - Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case. |
| 101 | + - A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects. |
| 102 | + |
| 103 | +- Updates to referenced standards |
| 104 | + |
| 105 | + - Update to <https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html> of JSON Schema Specification. |
| 106 | + - Update to <https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html> of JSON Schema Validation Specification. |
| 107 | + - Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON. |
| 108 | + - Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP. |
| 109 | + |
| 110 | +- Editorial changes |
| 111 | + |
| 112 | + - Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data. |
| 113 | + - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow. |
| 114 | + - Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. |
| 115 | + - Clarify that Request Body Objects need to specify at least one media type to be meaningful. |
| 116 | + - How to more clearly indicate that responses will not have a body. |
| 117 | + - Explanation and examples of headers including `Link` and `Set-Cookie`. |
| 118 | + - Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. |
| 119 | + - Extensive additional notes on parsing and serializing JSON and non-JSON data formats. |
| 120 | + |
| 121 | +## 3.1 Updates |
| 122 | + |
| 123 | +Version 3.1.2 has no material changes but does contain editorial fixes, additional examples, and clarifications. |
| 124 | + |
| 125 | +- Clarify that `$ref` in a Schema Object is a JSONSchema `$ref` keyword. |
| 126 | +- Detailed explanation of percent-encoding and -decoding, updated examples and references to match, including the Style Examples table. |
| 127 | +- Better explanation and examples for using Encoding and Serialization, and a note not to apply percent-encoding to headers. |
| 128 | +- Clarify that Request Body Objects need to specify at least one media type to be meaningful. |
| 129 | +- How to more clearly indicate that no response will have a body. |
| 130 | +- How to handle `null` in XML as an advisory note; since the functionality cannot be changed it is implementation-defined for 3.1 tooling. |
| 131 | +- Clarify that the root schema of an XML object should use the component name. |
| 132 | + |
| 133 | +<!-- vim: set ft=markdown tw=2 foldmethod=indent --> |
0 commit comments