diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 00f035fbfe..5b1ec60e81 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -182,12 +182,58 @@ It is the responsibility of an embedding format to define how to parse embedded When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operationObject), [Response Objects](#responseObject), [Reference Objects](#referenceObject), 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: -* As a full OpenAPI Description document (an [OpenAPI Object](#oasObject) taking up an entire document) +* As a complete OpenAPI Description document * As the Object type implied by its parent Object within the document * 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. +#### Resolving Implicit Connections + +Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD). + +These connections are easily resolved in single-document OADs, but the resolution process in multi-document OADs has never been spelled out, and is therefore _implementation-defined_, within the constraints described in this section. +In some cases, an unambiguous URI-based alternative is available, and OAD authors are RECOMMENDED to always use the alternative: + +Source | Target | Alternative +------ | ------ | ----------- +[Security Requirement Object](#securityRequirementObject) `{name}` | [Security Scheme Object](#securitySchemeObject) name under the [Components Object](#componentsObject) | _n/a_ +[Discriminator Object](#discriminatorObject) `mapping` _(implicit, or explicit name syntax)_ | [Schema Object](#schemaObject) name under the Components Object | `mapping` _(explicit URI syntax)_ +[Operation Object](#operationObject) `tags` | [Tag Object](#tagObject) `name` (in the Components Object) | _n/a_ +[Link Object](#linkObject) `operationId` | [Path Item Object](#pathItemObject) `operationId` | `operationRef` + +A fifth implicit connection, which involves appending the templated URL paths of the [Paths Object](#pathsObject) to the appropriate [Server Object](#serverObject)'s `url` field, is unambiguous because only the entry document's Paths Object contributes URLs to the described API. + +It is RECOMMENDED to consider all Operation Objects from all parsed documents when resolving any Link Object `operationId`. +This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. + +The implicit connections in the Security Requirement Object and Discriminator Object rely on the _component name_, which is the property name holding the component in the appropriate typed sub-object of the Components Object. +For example, the component name of the Schema Object at `#/components/schemas/Foo` is `Foo`. +The implicit connection of tags in the Operation Object use the `name` field of Tag Objects, which (like the Components Object) are found under the root OpenAPI Object. +This means that resolving component names and tag names both depend on starting from the correct OpenAPI Object. + +For resolving component and tag name connections from a referenced (non-entry) document, it is RECOMMENDED that tools support one or both of the following approaches, and it is likewise RECOMMENDED that OAD authors organize their documents to work well with them. +Note that neither approach changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets. + +##### OADs Using Only Complete Documents + +The approach in this section is RECOMMENDED for OADs that are composed entirely of complete documents. +Standalone JSON Schema documents can be included along with complete OpenAPI Documents as long as any Discriminator Objects within the standalone JSON Schemas only use explicit `mapping` URIs for all possible values. +This OAD design is RECOMMENDED when sharing components among multiple OADs. + +In this approach, each document is self-contained and resolves component and tag names to the Components Object and Tag Objects under its own root OpenAPI Object. + +**Note:** Currently, Security Requirement Objects do not support a URI-based mechanism for connecting to Security Scheme Objects, and Operation Objects do not support a URI-based mechanism for connecting to Tag Objects. +That means that in this approach, they can currently only connect to Security Scheme and Tag Objects within the same document. +This limitation is expected to be addressed in a future version of this specification. + +##### OADs With Only One OpenAPI Object + +The approach in this section is RECOMMENDED for OADs where the entry OpenAPI document is the only document containing an OpenAPI Object. +This approach is most suitable for splitting an otherwise self-contained single-document OAD into multiple documents for author convenience. + +In this approach, all component names are resolved through the entry document's Components Object, and all `operationId`s are resolved through Path Item Objects reachable through the `paths` or `webhooks` fields. + ### Data Types Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1).