Draft release notes for 3.2.0 and 3.1.2

draft-release-notes.md

@@ -0,0 +1,147 @@
+# [DRAFT]: Release Notes
+
+What's coming up? Look at `src/oas.md` on the relevant development branch for full details.
+
+## 3.2 Updates
+
+All the changes in the OpenAPI 3.2 release.
+
+### Headline features
+
+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.
+- `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`.
+
+#### 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.
+- 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.
+
+### 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.
+
+#### 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`.
+
+#### Multipart media types
+
+**TODO** this section with the additional items fields and examples.
+
+#### 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 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
+
+- 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.
+
+### 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
+
+- 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
+
+- 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.
+- 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
+
+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 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.
+
+<!-- vim: set ft=markdown tw=2 foldmethod=indent -->