Merge pull request #3732 from handrews/multi-parse

Limit interoperable parsing expectations (avoid type conflicts)

Author: lornajane

versions/3.1.1.md

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