Skip to content

Align 3.1.1 with 3.0.4 #3953

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 23, 2024
Merged

Align 3.1.1 with 3.0.4 #3953

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0be5ec
Editorial improvements from 3.0.4
ralfhandl Jul 12, 2024
be16865
Add links, remove confusing sentence
ralfhandl Jul 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 27 additions & 22 deletions versions/3.1.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,7 +365,6 @@ Field Name | Type | Description
<a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
<a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.


This object MAY be extended with [Specification Extensions](#specificationExtensions).

#### <a name="infoObject"></a>Info Object
Expand Down Expand Up @@ -433,7 +432,7 @@ Contact information for the exposed API.
Field Name | Type | Description
---|:---:|---
<a name="contactName"></a>name | `string` | The identifying name of the contact person/organization.
<a name="contactUrl"></a>url | `string` | The URI for to the contact information. This MUST be in the form of a URI.
<a name="contactUrl"></a>url | `string` | The URI for the contact information. This MUST be in the form of a URI.
<a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. This MUST be in the form of an email address.

This object MAY be extended with [Specification Extensions](#specificationExtensions).
Expand Down Expand Up @@ -819,13 +818,13 @@ components:
#### <a name="pathsObject"></a>Paths Object

Holds the relative paths to the individual endpoints and their operations.
The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering).
The path is appended to the URL from the [Server Object](#serverObject) in order to construct the full URL. The Paths Object MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering).

##### Patterned Fields

Field Pattern | Type | Description
---|:---:|---
<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [Server Object](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.

This object MAY be extended with [Specification Extensions](#specificationExtensions).

Expand Down Expand Up @@ -1113,12 +1112,12 @@ requestBody:
schema:
type: object
properties:
name:
description: Updated name of the pet
type: string
status:
description: Updated status of the pet
type: string
name:
description: Updated name of the pet
type: string
status:
description: Updated status of the pet
type: string
required:
- status
responses:
Expand Down Expand Up @@ -1512,7 +1511,7 @@ content:
$ref: '#/components/schemas/User'
examples:
user:
summary: User Example
summary: User example
externalValue: https://foo.bar/examples/user-example.json
application/xml:
schema:
Expand All @@ -1524,7 +1523,7 @@ content:
text/plain:
examples:
user:
summary: User example in Plain text
summary: User example in plain text
externalValue: https://foo.bar/examples/user-example.txt
'*/*':
examples:
Expand Down Expand Up @@ -1850,7 +1849,6 @@ requestBody:
# subschema, which is an object, so `application/json`
type: array
items:
type: object
$ref: '#/components/schemas/Address'
```

Expand Down Expand Up @@ -1926,9 +1924,9 @@ The documentation is not necessarily expected to cover all possible HTTP respons
However, documentation is expected to cover a successful operation response and any known errors.

The `default` MAY be used as a default response object for all HTTP codes
that are not covered individually by the `Responses Object`.
that are not covered individually by the Responses Object.

The `Responses Object` MUST contain at least one response code, and if only one
The Responses Object MUST contain at least one response code, and if only one
response code is provided it SHOULD be the response for a successful operation
call.

Expand Down Expand Up @@ -2137,7 +2135,7 @@ To describe incoming requests from the API provider independent from another API
##### Patterned Fields
Field Pattern | Type | Description
---|:---:|---
<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object, used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available.
<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available.

This object MAY be extended with [Specification Extensions](#specificationExtensions).

Expand Down Expand Up @@ -2394,7 +2392,7 @@ In this example, the JSON string had to be serialized before encoding it into th

#### <a name="linkObject"></a>Link Object

The `Link object` represents a possible design-time link for a response.
The Link Object represents a possible design-time link for a response.
The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.

Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response.
Expand Down Expand Up @@ -2790,8 +2788,15 @@ The OpenAPI Specification allows combining and extending model definitions using
`allOf` takes an array of object definitions that are validated *independently* but together compose a single object.

While composition offers model extensibility, it does not imply a hierarchy between the models.
To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword.
To support polymorphism, the OpenAPI Specification adds the `discriminator` field.
Copy link
Contributor Author

@ralfhandl ralfhandl Jul 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I cross-checked our predominant use of "keyword" and "field":

  • "keyword" if it is defined by JSON Schema
  • "field" if it is defined by OAS in one of the "Fixed Fields" sections

When used, the `discriminator` indicates the name of the property that hints which schema definition is expected to validate the structure of the model.
<!-- 3.0.4 contains the following text: does it also apply to 3.1.1?
As such, the `discriminator` field MUST be a required field.
There are two ways to define the value of a discriminator for an inheriting instance.
- Use the schema name.
- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism.
-->
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this 3.0.4 text also apply to 3.1.1?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ralfhandl this is separate from the changes I made - I don't think I ever touched this section (which is the section that #3951 is about). I can't recall the details of this MUST, but in #708 we apparently decided that the field would continue to be required.

Ideally, we would change this part in both versions, replacing "given id" with "component name" or "name within the Components Object":

As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.

This is confusing, because the "id" here is the name under the Components Object, not the $id keyword (which is supported in 3.1). I think I also avoided the phrase "inline schemas" when I did the other edits but can't remember right now- I'm less concerned about that.

Copy link
Contributor Author

@ralfhandl ralfhandl Jul 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This text is present in 3.1.0 and apparently got lost during the refactoring, adding it back now.

The last sentence is not only confusing, it is also wrong as one can use $ref pointing to an "inline schema" anywhere in the OpenAPI document.

Adjusted the text accordingly and will "backport" this to 3.0.4 once we agree.


###### Generic (Template) Data Structures

Expand Down Expand Up @@ -3313,7 +3318,7 @@ MyResponseType:
- $ref: '#/components/schemas/Lizard'
```

which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:
which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` field cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:

```yaml
MyResponseType:
Expand Down Expand Up @@ -3437,7 +3442,7 @@ Field Name | Type | Description

This object MAY be extended with [Specification Extensions](#specificationExtensions).

The `namespace` keyword is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:
The `namespace` field is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:

* Versions 3.1.0, 3.0.3, and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI", so authors using namespaces that include a fragment should check tooling support carefully.
* XML allows but discourages relative URI-references, while this specification outright forbids them.
Expand Down Expand Up @@ -3881,7 +3886,7 @@ description: Cert must be signed by example.com CA

```yaml
type: oauth2
flows:
flows:
implicit:
authorizationUrl: https://example.com/api/oauth/dialog
scopes:
Expand Down Expand Up @@ -4186,7 +4191,7 @@ Certain properties allow the use of Markdown which can contain HTML including sc

Version | Date | Notes
--- | --- | ---
3.1.1 | TBD | TBD
3.1.1 | TBD | Patch release of the OpenAPI Specification 3.1.1
3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0
3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification
3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification
Expand Down