Skip to content

Commit ffb4bbb

Browse files
lornajanelornajane
committed
Refactor into sections
1 parent 3b1d2eb commit ffb4bbb

1 file changed

Lines changed: 63 additions & 46 deletions

File tree

‎draft-release-notes.md‎

Lines changed: 63 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,25 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu
44

55
## 3.2 Updates
66

7-
### Support additional HTTP methods
7+
All the changes in the OpenAPI 3.2 release.
88

9-
- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.
10-
- 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`.
9+
### Headline features
10+
11+
A summary of the biggest changes.
1112

12-
### Nested, multipurpose tags
13+
#### Nested, multipurpose tags
1314

1415
- 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.
1516
- `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy.
1617
- `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).
1718
- A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.
1819

19-
### Document identity and URL resolution
20+
#### Support additional HTTP methods
21+
22+
- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.
23+
- 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`.
24+
25+
#### Document identity and URL resolution
2026

2127
- Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references.
2228
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
2531
- Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page.
2632
- API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI.
2733

28-
### Updated security schemes
34+
### Data modeling and representation
2935

30-
- 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`.
31-
- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata.
32-
- Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used).
33-
- Ability to reference a security scheme by URI rather than needing it declared in components.
36+
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.
3437

35-
### Servers
38+
#### Support for sequential media types
3639

37-
- Clarify that server URLs should not include fragment or query.
38-
- Support new `name` field alongside `description`, `url` and `variables`.
39-
- Formal path templating support for variable substitution in server urls, alongside guidance that each variable can only be used once in a URL.
40+
- 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.
41+
- Responses can be a repeating data structure, and are treated as if they are an array of schema objects.
42+
- Use `itemSchema` in a mediatype entry to describe each item.
43+
- Related: a new media types registry is published to give more context for each of the media types.
44+
- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads.
4045

41-
### Better polymorphic support
46+
#### Parameter and header changes
4247

43-
- The discriminator `propertyName` can now be an optional field.
44-
- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized.
45-
- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected.
46-
- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match.
47-
- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`.
48+
- 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.
49+
- Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values.
50+
- `allowReserved` field is now permitted on headers and on parameters with any value of `in`.
51+
- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context.
52+
- The `examples` (and older `example`) field is now supported with `content`.
4853

49-
### Path templating
54+
#### Multipart media types
5055

51-
**ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object.
56+
**TODO** this section with the additional items fields and examples.
5257

53-
### Improvements for APIs using XML as a content format
58+
#### Improvements for APIs using XML as a content format
5459

5560
- New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`.
5661
- `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
6065
- Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements.
6166
- Clarify that the root schema of an XML object should use the component name.
6267

63-
### Support for sequential media types
64-
65-
- 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.
66-
- Responses can be a repeating data structure, and are treated as if they are an array of schema objects.
67-
- Use `itemSchema` in a mediatype entry to describe each item.
68-
- Related: a new media types registry is published to give more context for each of the media types.
69-
- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads.
70-
71-
### Parameter and header changes
72-
73-
- 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.
74-
- Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values.
75-
- `allowReserved` field is now permitted on headers and on parameters with any value of `in`.
76-
- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context.
77-
- The `examples` (and older `example`) field is now supported with `content`.
78-
79-
### Show examples in both structure and serialized forms
68+
#### Show examples in both structure and serialized forms
8069

8170
- The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`.
8271
- `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
8877
- Summary of what to do: use `examples` over `example`, and use `dataValue` to show a clear, structured example of the data.
8978
If your use case could benefit from an example of how the data will look when it's transmitted, use `serializedValue` as well.
9079

91-
### Flexible response metadata fields
80+
### Additional features
81+
82+
That's not all! Here are the rest of the changes for this release.
83+
84+
#### Updated security schemes
85+
86+
- 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`.
87+
- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata.
88+
- Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used).
89+
- Ability to reference a security scheme by URI rather than needing it declared in components.
90+
91+
#### Servers
92+
93+
- Clarify that server URLs should not include fragment or query.
94+
- Support new `name` field alongside `description`, `url` and `variables`.
95+
- Formal path templating support for variable substitution in server urls, alongside guidance that each variable can only be used once in a URL.
96+
97+
#### Better polymorphic support
98+
99+
- The discriminator `propertyName` can now be an optional field.
100+
- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized.
101+
- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected.
102+
- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match.
103+
- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`.
104+
105+
#### Path templating
106+
107+
**ABNF** (Augmented Backus–Naur Form) formalised for path templating, server variables, and runtime expressions in the Links object.
108+
109+
#### Flexible response metadata fields
92110

93111
- `description` field for responses are now optional (they used to be required but they could be empty).
94112
- Additional `summary` field for responses, useful when displaying responses in a list context.
95113

96-
### Minor edits that are worth a mention
114+
#### Minor edits that are worth a mention
97115

98116
- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow.
99117
- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.
100118
- A new key `mediaTypes` is supported under `components` to support re-use of Media Type Objects.
101119

102-
### In-place updates to existing specifications and standards that we reference
120+
#### In-place updates to existing specifications and standards that we reference
103121

104122
- Update to <https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html> of JSON Schema Specification.
105123
- Update to <https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html> of JSON Schema Validation Specification.
106124
- Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON.
107125
- Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP.
108126

109-
### Editorial changes
127+
#### Editorial changes
110128

111129
- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data.
112130
- 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
120138

121139
Version 3.1.2 has no material changes but does contain editorial fixes.
122140

123-
- Clarification that Example Objects can be used in Header Objects.
124141
- Better explanation and examples for using Encoding.
125142
- Clarify that Request Body Objects need to specify at least one media type to be meaningful
126143
- How to more clearly indicate that no response will have a body
127144
- How to handle `null` in XML as an advisory note; since the functionality cannot be changed it is implementation-defined for 3.1 tooling.
128145
- Clarify that the root schema of an XML object should use the component name.
129146

130-
<!-- vim: set ft=markdown tw=2 foldmethod=indent: -->
147+
<!-- vim: set ft=markdown tw=2 foldmethod=indent -->

0 commit comments

Comments
 (0)