Skip to content

Commit

Permalink
Merge pull request #3732 from handrews/multi-parse
Browse files Browse the repository at this point in the history
Limit interoperable parsing expectations (avoid type conflicts)
  • Loading branch information
lornajane authored Apr 25, 2024
2 parents 84815b5 + ea38588 commit 6d1ca8e
Showing 1 changed file with 11 additions and 1 deletion.
12 changes: 11 additions & 1 deletion versions/3.1.1.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,10 +136,20 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA

### <a name="documentStructure"></a>OpenAPI Description Structure

An OpenAPI Description 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 Objects`](#referenceObject) and [`Schema Object`](#schemaObject) `$ref` keywords are used. In a multi-document description, the document containing the [OpenAPI Object](#oasObject) is known as the **entry OpenAPI document.**
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](#referenceObject), [Path Item Object](#pathItemObject) and [Schema Object](#schemaObject) `$ref` keywords, as well as the [Link Object](#linkObject) `operationRef` keyword, are used. In a multi-document description, the document containing the [OpenAPI Object](#oasObject) is known as the **entry OpenAPI document.**

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

#### <a name="structuralInteroperability"></a>Structural Interoperability

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 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.

### <a name="dataTypes"></a>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).
Expand Down

0 comments on commit 6d1ca8e

Please sign in to comment.