Skip to content

Commit a623fd1

Browse files
committed
Add a project glossary
This adds definitions and acronym expansions for terms that users of and potential contributors to OpenAPI projects are likely to encounter. It currently focuses on terms specific to OpenAPI, but could in the future also include some more standard terms to explain their usage in the OAS.
1 parent 66f45eb commit a623fd1

File tree

3 files changed

+49
-2
lines changed

3 files changed

+49
-2
lines changed

best-practices.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Best Practices
4-
nav_order: 4
4+
nav_order: 5
55
---
66

77
# Best Practices

glossary.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
layout: default
3+
title: Glossary
4+
nav_order: 3
5+
---
6+
7+
This page defines concepts that are important to understanding OpenAPI, as well as terms and acronyms you are likely to encounter if you want to contribute to the specification discussions.
8+
9+
# Acronyms
10+
11+
These acronyms are commonly used in OpenAPI discussions, and are defined in the following section.
12+
13+
- **BGB**: Business Governance Board
14+
- **OAD**: OpenAPI Description
15+
- **OAI**: OpenAPI Initiative
16+
- **OAS**: OpenAPI Specification
17+
- **SIG**: Special Interest Group
18+
- **TDC**: Technical Developer Community
19+
- **TSC**: Technical Steering Committee
20+
21+
# Definitions
22+
23+
- **Business Governance Board** (BGB): The group representing OAI members responsible for the initiatives budgets, trademarks, and possible future certification programs, as described in the [OAI Charter](https://www.openapis.org/participate/how-to-contribute/governance)
24+
- **document**: A local file, network resource, or other distinct entity in a particular format such as JSON or YAML
25+
- **entry document**: The document in an OAD where processing begins, starting with an OpenAPI Object ([3.0](https://spec.openapis.org/oas/v3.0.3#openapi-object), [3.1](https://spec.openapis.org/oas/v3.1.0#openapi-object))
26+
- **referenced documents**: The documents in an OAD that are not the entry document
27+
- **the Learn site**: This site, [learn.openapis.org](learn.openapis.org) ([repository](https://github.com/OAI/learn.openapis.org))
28+
- **Moonwalk**: Codename and SIG for the next (post-3.x) major release of the OAS ([announcement](https://www.openapis.org/blog/2023/12/06/openapi-moonwalk-2024), [repository](https://github.com/OAI/sig-moonwalk))
29+
- **OpenAPI Description** (OAD): One or more documents written according to a specific version of the OpenAPI Specification, that together describe an API
30+
- **OpenAPI Initiative** (OAI): The organization responsible for the development of the OpenAPI Specification _(not to be confused with the unrelated and more recent "OpenAI")_
31+
- **OpenAPI Specification** (OAS): The formal requirements for the OpenAPI format, which exists in several versions (e.g. 3.0.3, 3.1.0) ([repository](https://github.com/OAI/OpenAPI-Specification)
32+
- **Outreach Committee**: The group of volunteers dedicated to furthering the reach and impact of the OAS ([repository](https://github.com/OAI/Outreach))
33+
- **Overlay Specification**: A proposed specification from the overlays SIG ([repository](https://github.com/OAI/Overlay-Specification))
34+
- **Special Interest Group** (SIG): OpenAPI working groups focused on [specific topics](https://github.com/OAI/OpenAPI-Specification/blob/main/SPECIAL_INTEREST_GROUPS.md) related to the OAS or possible additional companion specifications
35+
- **Technical Developer Community** (TDC): The community of developers and specification-writers who work on and provide feedback to OpenAPI projects ([weekly Zoom calls](https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue+is%3Aopen+%22Open+Community+%28TDC%29+Meeting%22) are at 9AM US-Pacific)
36+
- **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)
37+
- **Workflows Specification**: A proposed specification from the workflows SIG ([repository](https://github.com/OAI/sig-workflows))
38+
39+
## A note on the history of "document", "definition", and "description"
40+
41+
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.
42+
43+
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.
44+
45+
## Documents and OpenAPI Descriptions
46+
47+
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`.

specification/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: The OpenAPI Specification Explained
4-
nav_order: 3
4+
nav_order: 4
55
has_children: true
66
has_toc: false
77
---

0 commit comments

Comments
 (0)