Skip to content
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

Jump to bottom

Fix description vs document terminology #4100

Open
wants to merge 6 commits into
base: v3.0.4-dev
Choose a base branch
from
+36 −33
Open

Fix description vs document terminology #4100

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e46084e
Fix description vs document terminology
mikekistler Sep 17, 2024
ce21969
Apply suggestions from PR review
mikekistler Sep 17, 2024
dfacec5
Commit suggestions from PR review.
mikekistler Sep 17, 2024
abddcf0
Updates based on TDC Meeting
mikekistler Oct 3, 2024
d447096
A few more document -> description changes
mikekistler Oct 2, 2024
c06c4fa
Address more PR review comments
mikekistler Oct 4, 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
57 changes: 29 additions & 28 deletions versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
An OpenAPI Description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

For examples of OpenAPI usage and additional documentation, please visit [[?OpenAPI-Learn]].

Expand Down Expand Up @@ -89,11 +89,11 @@ The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versionin

Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided.

An OpenAPI description document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses.
mikekistler marked this conversation as resolved.
Show resolved Hide resolved
An OpenAPI Description compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses.
mikekistler marked this conversation as resolved.
Show resolved Hide resolved
mikekistler marked this conversation as resolved.
Show resolved Hide resolved

### Format

An OpenAPI description document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
An OpenAPI Description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
mikekistler marked this conversation as resolved.
Show resolved Hide resolved

For example, if a field has an array value, the JSON array representation will be used:

Expand All @@ -115,25 +115,22 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
* Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [[JSON-Schema-05|JSON Schema]].
* Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).

**Note:** While APIs may be described by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
**Note:** While APIs may be described by OpenAPI Descriptions in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.

### OpenAPI Description Structure

An OpenAPI Description (OAD) MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object) and [Path Item Object](#path-item-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used.
An OpenAPI Description (OAD) MAY be structured as a single JSON or YAML document or composed from elements distributed across multiple documents at the discretion of the author. In the latter case, [Reference Object](#reference-object) and [Path Item Object](#path-item-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used to identify the documents containing the referenced elements.
mikekistler marked this conversation as resolved.
Show resolved Hide resolved

Any document consisting entirely of an [OpenAPI Object](#openapi-object) is known as a **syntactically complete OpenAPI document**.
An OpenAPI document that does _not_ reference any other documents is known as a **self-contained OpenAPI document**.
A single-document description is therefore _both_ syntactically complete _and_ self-contained.
In a multi-document description, the document containing the OpenAPI Object where parsing begins for a specific API's description is known as that API's **entry OpenAPI document**, or simply **entry document**.
In a multi-document OAD, the document containing the OpenAPI Object where parsing begins is known as that OAD's **entry document**.

It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`.
It is RECOMMENDED that the entry document of an OAD be named: `openapi.json` or `openapi.yaml`.

#### Structural Interoperability

When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on the parsing context. Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts:
JSON or YAML objects within an OAD are interpreted as specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on their context. Depending on how references are arranged, a given JSON or YAML object can be interpreted in multiple different contexts:

* As a syntactically complete OpenAPI Description document
* As the Object type implied by its parent Object within the document
* The root object of the entry document is interpreted as an OpenAPI Object
mikekistler marked this conversation as resolved.
Show resolved Hide resolved
mikekistler marked this conversation as resolved.
Show resolved Hide resolved
* As the Object type implied by its parent Object within the OpenAPI Description
Copy link
Member

Choose a reason for hiding this comment

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

This is another one where it's about the document. "parent Object within the OAD" is ambiguous- do you mean the literal parent in the JSON/YAML structure or the logical parent which might be a reference depending on how you reached it? This section was intended to clarify that distinction and the problems it can cause.

Here we are talking about the JSON/YAML structure parent.

While the presence of the next bullet point implies that this one has to be about something other than referencing, I would prefer to emphasize the document-oriented nature of the parent/child context.

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm in favour of "OpenAPI Description" here

Copy link
Member

Choose a reason for hiding this comment

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

This is still "OpenAPI Document" for the same reasons I stated previously- it is literally about the parent-child JSON/YAML relationship within the Document, and never about any other possible relationship within the Description. That is the entire purpose of this statement, and without that, the distinction between this bullet point and the next doesn't make any sense.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The example we discussed in the TDC meeting yesterday that I think swayed the group to conclude that "Description" is correct here is this:

entryDoc.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Multi-document OAD",
    "version": "1.0.0"
  },
  "paths": {
    "/path1": {
      "get": {
        "parameters": [
          {
            "$ref": "otherDoc.json#/param1"
          }
        ],
...

otherDoc.json

{
  "param1": {
    "name": "param1",
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
}

In this example, the parent object of "param1" in otherDoc.json is just a Json object -- it implies nothing about how to interpret param1. Rather, the interpretation of "param1" comes from it being referenced within the parameters array of entryDoc.json -- it's parent object in the OpenAPI Description.

Copy link
Member

@handrews handrews Oct 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

@mikekistler There are three bullet points here, which I will list with numbers even though they are not numbered in the text:

  1. The root object of the entry document is interpreted as an OpenAPI Object
  2. As the Object type implied by its parent Object within the OpenAPI Document
  3. As a reference target, with the Object type matching the reference source's context

Your example is point 3. Point 2 is also important - it's how parsing works before you resolve references. All three points are critical to properly handling OADs.

  1. You are told the entry document, and you start processing using context 1
  2. You parse that document, using the within-document parent-child relationships (context 2)
  3. You resolve references, evaluating reference targets using context 3

If the reference crosses to a different document, then, depending on how you wrote your parser (e.g. how Swagger's 3.0 parsing works vs how @darrelmiller says Microsoft's 3.0 parsing works), you can parse the same JSON/YAML object by both context 2 (which Microsoft uses even with 3.0 according to Darrel) and context 3 (which all implementations must use for proper reference resolution).

That is why the following paragraph exists:

If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as different Object types, the resulting behavior is implementation defined, and MAY be treated as an error if detected. An example would be referencing an empty Schema Object under #/components/schemas where a Path Item Object is expected, as an empty object is valid for both types. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios.

Please stop trying to change context 2 to be the same as context 3. The entire point of the "Structural Interoperability" section is to point out that different implementations use these contexts and they don't always say the same thing.

Your change completely guts this section. Your example is about context 3. But context 2 is also critically important and cannot be removed. You literally cannot parse a document without it. How do you know that the child of the info field is an Info Object? Context 2 is what tells you that. There is no context 3 for that field.

Whenever someone writes a $ref to something that is also part of a well-formed OpenAPI Document, context 2 and 3 both apply and they can be different.

Your example only uses context 3. But that does not invalidate context 2.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hmmm. Okay ... I see your point about the overlap between 2 and 3.

But I still think there is a problem with using "OpenAPI Document" in bullet 2, and I think it is illustrated by the same example as given above.

What is the context for the value of the "schema" field within otherDoc.json? If bullet 2 is about "OpenAPI Document", then it doesn't apply because otherDoc.json is not an "OpenAPI Document" (by the definition we have now added), and bullet 3 also does not apply since this is not a reference target.

If we make bullet 2 be only about OpenAPI documents, then we'll need to add another bullet for documents that are not OpenAPI documents.

Copy link
Member

Choose a reason for hiding this comment

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

Due to the way the document flow was broken by the comment I had missed the third bullet point. This contributed to me misunderstanding what the second point was trying to say.

In the tooling my team builds, when parsing an OpenAPI document that has been referenced, we don't use the context of the reference (context 3) to determine the type of the thing beingback to the probele referenced. If someone attempts to reference a schema in a location that expects a parameter, we give a type mismatch error. We don't attempt to parse the schema as if it was a parameter. We would only do that when pointing to a document that is not an OpenAPI Document.

But as Henry states, this is implementation dependent. Tooling that is building an OpenAPI document editing experience would always use the structural context (context 2) to determine the type of something. Whereas a a tool that is just consuming an OpenAPI document could easily choose to use context 3 for determining the type of a reference target.

Going back to the debated terminology, the phrase "OpenAPI Description" is problematic because you could argue that the parent object in context 2 is not actually part of the OpenAPI Description. However, if you say "OpenAPI Document" you a) know explicitly which parent you are talking about and b) know that tooling can parse the OpenAPI document and know the type of the parent object.

So, apologies to everyone involved but I am going to reverse my opinion from what I said on Thursday and say this needs to say OpenAPI Document.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Okay, I can see the argument for this. But then which of bullet do you say explains the context used for parsing/interpreting the value of "schema" in otherDoc.json?

* As a reference target, with the Object type matching the reference source's context

If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. An example would be referencing an empty Schema Object under `#/components/schemas` where a Path Item Object is expected, as an empty object is valid for both types. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios.
Expand Down Expand Up @@ -249,13 +246,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr

#### OpenAPI Object

This is the root object of the [OpenAPI document](#openapi-description).
This is the root object of the [OpenAPI Description](#openapi-description).
lornajane marked this conversation as resolved.
Show resolved Hide resolved

##### Fixed Fields

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="oas-version"></a>openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is _not_ related to the API [`info.version`](#info-version) string. |
| <a name="oas-version"></a>openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI Description uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Description. This is _not_ related to the API [`info.version`](#info-version) string. |
mikekistler marked this conversation as resolved.
Show resolved Hide resolved
| <a name="oas-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. |
| <a name="oas-servers"></a>servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. |
| <a name="oas-paths"></a>paths | [Paths Object](#paths-object) | **REQUIRED**. The available paths and operations for the API. |
Expand All @@ -280,7 +277,7 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi
| <a name="info-terms-of-service"></a>termsOfService | `string` | A URL for the Terms of Service for the API. This MUST be in the form of a URL. |
| <a name="info-contact"></a>contact | [Contact Object](#contact-object) | The contact information for the exposed API. |
| <a name="info-license"></a>license | [License Object](#license-object) | The license information for the exposed API. |
| <a name="info-version"></a>version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described). |
| <a name="info-version"></a>version | `string` | **REQUIRED**. The version of the OpenAPI Description (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described). |
mikekistler marked this conversation as resolved.
Show resolved Hide resolved

This object MAY be extended with [Specification Extensions](#specification-extensions).

Expand Down Expand Up @@ -383,7 +380,7 @@ An object representing a Server.

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="server-url"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. |
| <a name="server-url"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the entry document of the OpenAPI Description is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. |
Comment on lines -386 to +385
Copy link
Member

Choose a reason for hiding this comment

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

I think this might also be document. It doesn't matter for Server Objects under the OpenAPI Object's servers field, and if there are no such Server Objects, then we're basically "pretending" that there is one with a url based on the entry document's location.

But this gets weird when you have a Path Item Object in a referenced document that defines its own servers, or that has Operation Objects that define their own servers (or a Link Object that defines server). I think those ought to be relevant to the location of the document in which they appear.

In "Resolving Implicit Connections", I hand-waved the Servers problem on the grounds that only the entry document's Paths Object is relevant. But with a shared Path Item Object under the Components Object of a components-only "syntactically complete" document, do you look up the default by current document or by entry document? That might actually need clarification.

Copy link
Contributor

Choose a reason for hiding this comment

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

In "Resolving Implicit Connections", I hand-waved the Servers problem on the grounds that only the entry document's Paths Object is relevant. But with a shared Path Item Object under the Components Object of a components-only "syntactically complete" document, do you look up the default by current document or by entry document? That might actually need clarification.

It would seem logical to me then the lookup happens on the entry document.

Copy link
Member

Choose a reason for hiding this comment

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

This ought to follow RFC3986 which would go:

  • RFC3986 §5.1.2 enclosing context (OAS 3.0 has always violated RFC3986 by skipping this)
  • RFC3986 §5.1.3 retrieval URL of the resource, which in this case would be the current document
  • RFC3986 §5.1.4 application-specific default, which could be anything we want

Do we state anywhere how to locate Server Objects from referenced (non-entry) documents that are OpenAPI Documents and therefore might have an OpenAPI Object (and servers field) in the document root that is not the OAD root (which is always the entry document)?

| <a name="server-description"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
| <a name="server-variables"></a>variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. |

Expand Down Expand Up @@ -2152,7 +2149,7 @@ Because examples using these fields represent the final serialized form of the d
The singular `example` field in the Parameter or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`.

Some examples cannot be represented directly in JSON or YAML.
For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of the OpenAPI Description document.
For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of the OpenAPI Description.
mikekistler marked this conversation as resolved.
Show resolved Hide resolved
With the Example Object, such values can alternatively be handled through the `externalValue` field.

##### Example Object Examples
Expand Down Expand Up @@ -2302,7 +2299,7 @@ For computing links and providing instructions to execute them, a [runtime expre

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="link-operation-ref"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operation-object). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operation-object) in the OpenAPI description. |
| <a name="link-operation-ref"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operation-object). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operation-object) in the OpenAPI Description. |
Copy link
Member

Choose a reason for hiding this comment

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

Does this mean that operationRef can only point to a resource/document that is already part of the OAD due to the action of another keyword? This is relevant to the text early in the spec that states what keywords are allowed to connect parts into an OAD. (but see next comment in the Reference Object)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I don't read it that way. Though I do find the terminology "A relative or absolute URI reference" a bit strange. I think that URI references are either relative refs or URIs, and URIs may be absolute or not, but I don't think "an absolute URI reference" is a thing. This is the only place this phrase occurs in the spec. I think "URI reference" is clearer and more accurate, so I'll make that change. Also open to additional changes if you think they are needed.

Copy link
Member

Choose a reason for hiding this comment

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

"URI reference" in RFC3986 is the most generic term. Anything vaguely URI-ish (relative, absolute, full) is technically A URI reference (often written "URI-reference").

But you are right that this needs to be changed for a different reason: https://example.com/foo#/components/pathItems/bar/get is a URI-reference that is neither relative (because it has a scheme) nor absolute (because it has a fragment).

| <a name="link-operation-id"></a>operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. |
| <a name="link-parameters"></a>parameters | Map[`string`, Any \| [{expression}](#runtime-expressions)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used (optionally qualified with the parameter location, e.g. `path.id` for an `id` parameter in the path), whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. |
| <a name="link-request-body"></a>requestBody | Any \| [{expression}](#runtime-expressions) | A literal value or [{expression}](#runtime-expressions) to use as a request body when calling the target operation. |
Expand Down Expand Up @@ -2592,7 +2589,7 @@ description: Pets operations

#### Reference Object

A simple object to allow referencing other components in the OpenAPI document, internally and externally.
A simple object to allow referencing other components in the OpenAPI Description, internally and externally.
Copy link
Member

Choose a reason for hiding this comment

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

This suggests that "in the OAD" means "in the OAD, including documents that are only part of the OAD because of this Reference Object", which would mean that operationRef above, with similar wording, can also pull in otherwise-unconnected documents. Is this how this wording is intended?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm not sure what you mean by "otherwise-unconnected documents" -- I think $ref is a thing that connects documents. But perhaps to directly answer your question -- I think it is intended for $ref to be able to reference any document, whether or not it was somehow "connected" through some other means.

Copy link
Member

Choose a reason for hiding this comment

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

Yes, $ref has to be able to do that. I'm pointing out that I find that the language suggests to me that the document has to somehow already be part of the OAD, but the only way we define to connect things is $ref/operationRef/mapping. For $ref it's (to us) self-evident that there's no other way, but for operationRef and mapping this wording could be read to say that you can only point operationRef and mapping to a document that has already been $ref'd. So this comment is really more about operationRef and mapping.


The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules.

Expand Down Expand Up @@ -3076,7 +3073,7 @@ However, the exact nature of such conversions are implementation-defined.

##### Examples

For these examples, assume all schemas are in the entry OpenAPI document; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections).
For these examples, assume all schemas are in a single-document OpenAPI Description; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections).
mikekistler marked this conversation as resolved.
Show resolved Hide resolved
mikekistler marked this conversation as resolved.
Show resolved Hide resolved

In OAS 3.0, a response payload MAY be described to be exactly one of any number of types:

Expand All @@ -3100,7 +3097,7 @@ MyResponseType:
propertyName: petType
```

The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OpenAPI description. Thus the response payload:
The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OpenAPI Description. Thus the response payload:

```json
{
Expand Down Expand Up @@ -3802,7 +3799,7 @@ The extensions properties are implemented as patterned fields that are always pr

The OpenAPI Initiative maintains several [[OpenAPI-Registry|extension registries]], including registries for [individual extension keywords](https://spec.openapis.org/registry/extension/) and [extension keyword namespaces](https://spec.openapis.org/registry/namespace/).

Extensions are one of the best ways to prove the viability of proposed additions to the specification.
Extensions are one of the best ways to prove the viability of proposed additions to the specification.
It is therefore RECOMMENDED that implementations be designed for extensibility to support community experimentation.

Support for any one extension is OPTIONAL, and support for one extension does not imply support for others.
Expand All @@ -3821,9 +3818,9 @@ Two examples of this:

## Security Considerations

### OpenAPI Document Formats
### OpenAPI Description Formats

OpenAPI description documents use JSON, YAML, and JSON Schema, and therefore share their security considerations:
OpenAPI Descriptions use a combination of JSON, YAML, and JSON Schema, and therefore share their security considerations:

* [JSON](https://www.iana.org/assignments/media-types/application/json)
* [YAML](https://www.iana.org/assignments/media-types/application/yaml)
Expand All @@ -3832,15 +3829,19 @@ OpenAPI description documents use JSON, YAML, and JSON Schema, and therefore sha

### Tooling and Usage Scenarios

In addition, OpenAPI description documents are processed by a wide variety of tooling for numerous different purposes, such as client code generation, documentation generation, server side routing, and API testing. OpenAPI description authors must consider the risks of the scenarios where the OpenAPI description may be used.
In addition, OpenAPI Descriptions are processed by a wide variety of tooling for numerous different purposes, such as client code generation, documentation generation, server side routing, and API testing. OpenAPI Description authors must consider the risks of the scenarios where the OpenAPI Description may be used.

### Security Schemes

An OpenAPI description describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations.
An OpenAPI Description describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations.

### Handling External Resources

OpenAPI description documents may contain references to external resources that may be dereferenced automatically by consuming tools. External resources may be hosted on different domains that may be untrusted. References in an OpenAPI document, or across OpenAPI documents within a multi-document OpenAPI description, may cause a cycle. Tooling must detect and handle cycles to prevent resource exhaustion.
OpenAPI Descriptions may contain references to external resources that may be dereferenced automatically by consuming tools. External resources may be hosted on different domains that may be untrusted.

### Handling Reference Cycles

References in an OpenAPI Description may cause a cycle. Tooling must detect and handle cycles to prevent resource exhaustion.

### Markdown and HTML Sanitization

Expand Down