Limit interoperable parsing expectations

As discovered through the OASComply project, certain referencing
scenarios are ambiguous, with different authorities holding
contradictory interpretations regarding whether and how they are
to be supported.  As a result, it is impossible to define
compliance, as all of the interpretations can be argued to be
"correct" in some sense.

This change excludes some particularly challenging scenarios from
compliance testing by making their behavior explicitly
implementation-defined.  This has several benefits:

* No current implementation is rendered non-compliant
* No currently usable OAD is rendered invalid
* New implementers need not put effort into handling these scenarios
* User expectations are set to _not_ expect consistent behavior
* Linters can write a rule to match these expectations
* Everyone is guided towards straightforwad best practices

Includes substantially better wording from ralfhandl from
review comments for the 3.1.1 version of this change.

Co-authored-by: Ralf Handl <[email protected]>

Author: handrews

Diff for: versions/3.0.4.md

@@ -146,10 +146,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, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](https://json-schema.org) definitions.  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
 
 Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).