You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: draft-release-notes.md
+48-48Lines changed: 48 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,36 +6,36 @@ What's coming up? Look at `src/oas.md` on the relevant development branch for fu
6
6
7
7
### Support additional HTTP methods
8
8
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
+
- 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`.
11
11
12
12
### Nested, multipurpose tags
13
13
14
-
- 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.
15
-
-`parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy.
16
-
-`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).
17
-
- A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.
14
+
- 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.
15
+
-`parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy.
16
+
-`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).
17
+
- A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.
18
18
19
19
### Updated security schemes
20
20
21
-
- 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`.
22
-
- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata.
23
-
- Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used).
24
-
- Ability to reference a security scheme by URI rather than needing it declared in components.
21
+
- 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`.
22
+
- Additional security scheme field: `oauth2MetadataUrl` URL for auth server metadata.
23
+
- Additional `deprecated` field for security schemes (indicating that the scheme may still be supported, but that it should not be used).
24
+
- Ability to reference a security scheme by URI rather than needing it declared in components.
25
25
26
-
### Servers
26
+
### Servers
27
27
28
-
- Clarify that server URLs should not include fragment or query.
29
-
- Support new `name` field alongside `description`, `url` and `variables`.
30
-
- Formal path templating support for variable substitution in server urls.
28
+
- Clarify that server URLs should not include fragment or query.
29
+
- Support new `name` field alongside `description`, `url` and `variables`.
30
+
- Formal path templating support for variable substitution in server urls.
31
31
32
32
### Better polymorphic support
33
33
34
-
- The discriminator `propertyName` can now be an optional field.
35
-
- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized.
36
-
- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected.
37
-
- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match.
38
-
- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`.
34
+
- The discriminator `propertyName` can now be an optional field.
35
+
- Additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized.
36
+
- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected.
37
+
- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match.
38
+
- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`.
39
39
40
40
### Reference resolution
41
41
@@ -47,52 +47,52 @@ Additional top-level `$self` to be used as a base URI for resolving references i
47
47
48
48
### Improvements for APIs using XML as a content format
49
49
50
-
- New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`.
51
-
-`attribute: true` deprecated in favor of `nodeType: attribute`.
52
-
-`wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility).
53
-
- The `xml` keyword can be used in any Schema Object.
54
-
- XML namespaces can be IRIs (rather than URIs).
55
-
- Explanation and example on how to handle `null` in XML.
56
-
- Clarify that the root schema of an XML object should use the component name.
50
+
- New `nodeType` field allows mapping schemas to common XML node types: `element`, `attribute`, `text`, `cdata`, or `none`.
51
+
-`attribute: true` deprecated in favor of `nodeType: attribute`.
52
+
-`wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility).
53
+
- The `xml` keyword can be used in any Schema Object.
54
+
- XML namespaces can be IRIs (rather than URIs).
55
+
- Explanation and example on how to handle `null` in XML.
56
+
- Clarify that the root schema of an XML object should use the component name.
57
57
58
58
### Support for sequential media types
59
59
60
-
- 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.
61
-
- Responses can be a repeating data structure, and are treated as if they are an array of schema objects.
62
-
- Use `itemSchema` in a mediatype entry to describe each item.
63
-
- Related: a new media types registry is published to give more context for each of the media types.
64
-
- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads.
60
+
- 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.
61
+
- Responses can be a repeating data structure, and are treated as if they are an array of schema objects.
62
+
- Use `itemSchema` in a mediatype entry to describe each item.
63
+
- Related: a new media types registry is published to give more context for each of the media types.
64
+
- Also a "Complete vs Streaming Content" section for guidance on streaming binary payloads.
65
65
66
66
### Parameter and header changes
67
67
68
-
- 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.
69
-
- Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values.
70
-
-`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).
71
-
- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context.
72
-
68
+
- 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.
69
+
- Parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values.
70
+
-`allowReserved` field is now permitted on headers and on parameters with any value of `in`.
71
+
- Remove incorrect mention of Reference Object in the header `schema` field. The JSONSchema ref would be the correct thing to use in this context.
72
+
73
73
### Flexible response metadata fields
74
74
75
-
-`description` field for responses are now optional (they used to be required but they could be empty).
76
-
- Additional `summary` field for responses, useful when displaying responses in a list context.
75
+
-`description` field for responses are now optional (they used to be required but they could be empty).
76
+
- Additional `summary` field for responses, useful when displaying responses in a list context.
77
77
78
78
### Minor edits that are worth a mention
79
79
80
-
- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow.
80
+
- Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow.
81
81
82
82
### In-place updates to existing specifications and standards that we reference
83
83
84
-
- Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html of JSON Schema Specification.
85
-
- Update to https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html of JSON Schema Validation Specification.
86
-
- Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON.
87
-
- Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP.
84
+
- Update to <https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html> of JSON Schema Specification.
85
+
- Update to <https://www.ietf.org/archive/id/draft-bhutton-json-schema-validation-01.html> of JSON Schema Validation Specification.
86
+
- Use [RFC8529](https://tools.ietf.org/html/rfc8259) for JSON.
87
+
- Use [RFC9110](https://tools.ietf.org/html/rfc9110) for HTTP.
88
88
89
89
### Editorial changes
90
90
91
-
- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data.
92
-
- Clarification that Example Objects can be used in Header Objects.
93
-
- Better explanation and examples for using Encoding.
94
-
- Clarify that Request Body Objects need to specify at least one media type to be meaningful.
95
-
- How to more clearly indicate that responses will not have a body.
91
+
- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data.
92
+
- Clarification that Example Objects can be used in Header Objects.
93
+
- Better explanation and examples for using Encoding.
94
+
- Clarify that Request Body Objects need to specify at least one media type to be meaningful.
95
+
- How to more clearly indicate that responses will not have a body.
0 commit comments