Skip to content

Commit

Permalink
Move historical note to the end...
Browse files Browse the repository at this point in the history
...where it should have been in the first place.  Oops.
  • Loading branch information
handrews committed Feb 29, 2024
1 parent 5246c2b commit 02f3b42
Showing 1 changed file with 4 additions and 4 deletions.
8 changes: 4 additions & 4 deletions glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,12 @@ These acronyms are commonly used in OpenAPI discussions, and are defined in the
- **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)
- **Workflows Specification**: A proposed specification from the workflows SIG ([repository](https://github.com/OAI/sig-workflows))

## Documents and OpenAPI Descriptions

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

## A note on the history of "document", "definition", and "description"

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.

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.

## Documents and OpenAPI Descriptions

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 comments on commit 02f3b42

Please sign in to comment.