Skip to content

Commit 02f3b42

Browse files
committed
Move historical note to the end...
...where it should have been in the first place. Oops.
1 parent 5246c2b commit 02f3b42

File tree

1 file changed

+4
-4
lines changed

1 file changed

+4
-4
lines changed

glossary.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,12 @@ These acronyms are commonly used in OpenAPI discussions, and are defined in the
3737
- **Technical Steering Committee** (TSC): The [group of people](https://github.com/OAI/OpenAPI-Specification/blob/main/MAINTAINERS.md) charged with stewarding the OAI's specification work, as described in the [OAI Charter](https://www.openapis.org/participate/how-to-contribute/governance)
3838
- **Workflows Specification**: A proposed specification from the workflows SIG ([repository](https://github.com/OAI/sig-workflows))
3939

40+
## Documents and OpenAPI Descriptions
41+
42+
An OpenAPI Description, or OAD, can be structured as one or more documents, connected by references. Those documents are typically stored as local files with `.json` or `.yaml` (or `.yml`) extensions, or as HTTP-accessible network resources of type `application/openapi+json` or `application/openapi+yaml`.
43+
4044
## A note on the history of "document", "definition", and "description"
4145

4246
Up through OAS 3.0.3 and 3.1.0, the OAS contained a section titled "OpenAPI Document", with differing definintions depending the OAS version. The terms "OpenAPI Definition", "OpenAPI Description", and other variations and combinations were also used within the specification and/or the [learn.openapips.org](learn.openapis.org) site.
4347

4448
In September 2023, the OAI Technical Steering Committee (TSC) agreed to standardize on "OpenAPI Description" for the complete logical entity that describes an API, and to reserve the term "document" (lower-cased) for its common meaning. Resolving the debate between "OpenAPI Description" and "OpenAPI Definition" hinged on the observation that while "definition" is appropriate when the API code is generated from the OAD, it is not accurate when an OAD is written for an existing API. The term "description" is accurate in both cases.
45-
46-
## Documents and OpenAPI Descriptions
47-
48-
An OpenAPI Description, or OAD, can be structured as one or more documents, connected by references. Those documents are typically stored as local files with `.json` or `.yaml` (or `.yml`) extensions, or as HTTP-accessible network resources of type `application/openapi+json` or `application/openapi+yaml`.

0 commit comments

Comments
 (0)