From 2f547da7e12de5eea8d1b3cedf554d5a0e8ded43 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 26 Aug 2024 09:32:33 -0700 Subject: [PATCH 1/2] "Object" def, "with" in titles, fix level Define capital-O "Object" to make it clear why it is only occasionally capitalized. Use lowercase "with" in titles consistently (it was more common than capitalized "With". This is one of those rules that is different depending on whose style guide you use- about half the major guides say always lowercase, the other say always captial. We were using lowercase more often. Also, fix "Working with Examples" to be a subsection of the Example Object as otherwise it breaks the pattern of all of the headings of its level being Object definitions. I remember messing with this a lot when I first posted that PR and either I just missed this or I had some reason I have now forgotten to do it this way. --- versions/3.1.1.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 6ba383541c..c1b709c87e 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -28,6 +28,10 @@ A "schema" is a formal description of syntax and structure. This document serves as the [schema](#schema) for the OpenAPI Specification format; a non-authoritative JSON Schema based on this document is also provided on [spec.openapis.org](https://spec.openapis.org) for informational purposes. This specification also _uses_ schemas in the form of the [Schema Object](#schema-object). +### Object + +When capitalized, the word "Object" refers to any of the Objects that are named by section headings in this document. + ### Path Templating Path templating refers to the usage of template expressions, delimited by curly braces (`{}`), to mark a section of a URL path as replaceable using path parameters. @@ -229,7 +233,7 @@ The formats defined by the OAS are: As noted under [Data Type](#data-types), both `type: number` and `type: integer` are considered to be numbers in the data model. -#### Working With Binary Data +#### Working with Binary Data The OAS can describe either _raw_ or _encoded_ binary data. @@ -2199,7 +2203,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten In all cases, the example value SHOULD be compatible with the schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. -#### Working With Examples +##### Working with Examples Example Objects can be used in both [Parameter Objects](#parameter-object) and [Media Type Objects](#media-type-object). In both Objects, this is done through the `examples` (plural) field. @@ -2697,7 +2701,7 @@ $ref: '#/components/schemas/Pet' $ref: Pet.yaml ``` -##### Relative Documents With Embedded Schema Example +##### Relative Documents with Embedded Schema Example ```json { @@ -4295,7 +4299,7 @@ when expanded with the data given earlier, we get: ?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun ``` -#### Expansion With Non-RFC6570-Supported Options +#### Expansion with Non-RFC6570-Supported Options But now let's say that (for some reason), we really want that `/` in the `b` formula to show up as-is in the query string, and we want our words to be space-separated like in a written phrase. To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: "spaceDelimited"` for `words`: From fdace9f2bccba75ae3724056e830ac2b8677a83b Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 27 Aug 2024 15:31:32 -0700 Subject: [PATCH 2/2] Fix two capital-O Objects These got lower-cased because I did not explain in the text that the capital is significant. The previous commit adds the explanation (ported from 3.0.4) and this fixes the 3.1.1-specific occurrences. --- versions/3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index c1b709c87e..b76582a24a 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -139,8 +139,8 @@ Implementations MAY support complete-document parsing in any of the following wa * Detecting OpenAPI or JSON Schema documents using media types * Detecting OpenAPI documents through the root `openapi` field * Detecting JSON Schema documents through detecting keywords or otherwise successfully parsing the document in accordance with the JSON Schema specification -* Detecting a document containing a referenceable object at its root based on the expected type of the reference -* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root object +* Detecting a document containing a referenceable Object at its root based on the expected type of the reference +* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object Implementations that parse referenced fragments of OpenAPI content without regard for the content of the rest of the containing document will miss keywords that change the meaning and behavior of the reference target. In particular, failing to take into account keywords that change the base URI introduces security risks by causing references to resolve to unintended URIs, with unpredictable results.