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

This particular scenario, where the same JSON/YAML object is
parsed in different semantic contexts, is well-defined if the
requirements of 2.0 are assumed to apply despite no longer
appearing in the text.  However, the scenario is *not*
well-defined in 3.1, so we should advise against it.

While the 3.1 version of this change made the scenario explicitly
implementation-defined, it seems better to acknowledge the
assumption here while still noting that it is not clearly required.

This also removes the confusing reference to JSON Schema for "$ref"
as the Reference Object *explicitly* states that it is governed
by JSON Reference and *not* JSON Schema.  It also enumerates
more of the referencing keywords like we do in 3.1.

Author: handrews

versions/3.0.4.md

@@ -133,10 +133,22 @@ 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) and [Path Item Object](#pathItemObject) `$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
+
+In version 2.0 of this specification, this section specified that the OAD is a "single file", which (together with the treatment of `$ref` as a URL resolved separately each time it is encountered), resulted in the common interpretation that if the same object is parsed multiple times in contexts that require it to be parsed as _different_ Object types, then as long as the reference target is valid for each Object type, then there is no error.  An example would be parsing an empty JSON object as a reference target twice: Once as a Path Item Object and once as a Schema Object.  Since both Object types allow empty objects, this is syntactically valid for both Objects.
+
+This approach to conflicting contexts remains valid in version 3.0, although it is not required by this version's text.  However, it is RECOMMENDED that description authors avoid such scenarios to maximize the portability of their OADs across tools, and to version 3.1, where the result of such conflicting contexts is _implementation-defined_ and MAY be treated as an error.
+
 ### <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).