Skip to content

Commit

Permalink
Apply suggestions from PR review
Browse files Browse the repository at this point in the history
Co-authored-by: Ralf Handl <[email protected]>
  • Loading branch information
mikekistler and ralfhandl authored Sep 17, 2024
1 parent e46084e commit ce21969
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions versions/3.0.4.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
* Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [[JSON-Schema-05|JSON Schema]].
* Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).

**Note:** While APIs may be described by OpenAPI Description in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
**Note:** While APIs may be described by OpenAPI Descriptions in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.

### OpenAPI Description Structure

Expand All @@ -130,7 +130,7 @@ It is RECOMMENDED that the entry document of an OAD be named: `openapi.json` or
JSON or YAML objects within an OAD are interpreted as specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on their context. Depending on how references are arranged, a given JSON or YAML object can be interpreted in multiple different contexts:

* The root object of the entry document is interpreted as an OpenAPI Object
* As the Object type implied by its parent Object within the description
* As the Object type implied by its parent Object within the OpenAPI Description
* 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.
Expand Down

0 comments on commit ce21969

Please sign in to comment.