Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved readability, grammar, and correct name usage of OAI, OAS, an… #20

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Improved readability, grammar, and correct name usage of OAI, OAS, an… #20

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9a34426
Improved readability, grammar, and correct name usage of OAI, OAS, an…
clairestreb Sep 16, 2019
ebcd3c3
Updates after review
clairestreb Sep 21, 2019
36590b5
Clarify the spec format itself vs documents that use it
clairestreb Sep 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 21 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,67 @@
# The OpenAPI Initiative Style Guide

How to (and how not to) refer to the OAI in meetups, interviews, casual conversations, the settling of bar bets, and for conference presentations.
How to (and how not to) refer to the **OpenAPI Initiative (OAI)** and the **OpenAPI Specification (OAS)** in meetups, interviews, casual conversations, the settling of bar bets, and for conference presentations.

## The Specification Name and Usage

**OpenAPI Specification** refers the name of the popular API description format. It contains ONE space and FIVE capital letters. Following the first instance, it may be referred to as:
The OAS refers to the name of the popular API description format. It contains ONE space and FIVE capital letters. Following the first instance, it may be referred to as:
clairestreb marked this conversation as resolved.
Show resolved Hide resolved

* **OAS**: for example, *"Can you send us your OAS document?"*
| USAGE | EXAMPLE | COMMENT |
| :-------------------- | :------------------------------------------------------- | :---------------------------------------- |
| **OAS** | *Can you send us your OAS document?* | |
| **Specification**<br/>or<br/>**Spec** | *Can you send me your specification?* | |
| **OpenAPI** | *OpenAPI has a different signature mechanism than WSDL.* | Use when comparing to a different format. |
clairestreb marked this conversation as resolved.
Show resolved Hide resolved

* **Specification**: for example *"Can you send me your specification?"* (may be abbreviated less formally as "spec")

* **OpenAPI** (when referring to the format in comparison to another): such as *"OpenAPI has a different signature mechanism than WSDL."*

In order to connect readers familiar with the former name of the specification it may be introduced as, *"The OpenAPI Specification, formerly known as the Swagger specification."* (Note that if Swagger is mentioned in this way, it should be accompanied by the word "specification" as Swagger remains SmartBear's trademark for certain open source tools.)
To connect readers familiar with the former name of the specification, it may be introduced as *"The OpenAPI Specification, formerly known as the Swagger specification."* **Note:** If Swagger is mentioned in this way, it should be accompanied by the word "specification," because Swagger remains SmartBear's trademark for certain open source tools.

## The Initiative Name and Usage

The **OpenAPI Initiative** refers to the organization that oversees the specification. It must contain ONE space and FIVE capital letters. After the initial declaration, it may be referred to as the "OAI" in subsequent references, for example:
The **OpenAPI Initiative** refers to the organization that oversees the specification. Its name must contain ONE space and FIVE capital letters. After the initial declaration, it may be referred to as the "OAI" in subsequent references, for example:

* *The OpenAPI Specification (OAS) provides an open governance model, as directed by the OpenAPI Initiative's charter. The specification, although managed by the OAI, is not the same as the initiative itself.*
> *The OpenAPI Initiative (OAI) directs the OpenAPI Specification (OAS) that provides an open governance model. The specification, although managed by the OAI, is not the same as the initiative itself.*

## Guidelines for Naming Projects, Tools, or Organizations

If you are creating something that works with or depends upon the OpenAPI Specification, you may decide you would like to use `OpenAPI` in the name of said thing. In these cases, it is important to consider whether your audience might confuse your effort as being under the auspices of the OpenAPI Initiative. Ask yourself, "Might someone think this was an official tool/project/group of the OAI?" If the answer is, "Maybe," then consider adding a modifier. For example, `OpenAPI Tools` vs `OpenAPI-based Tools` or even `Tools for OpenAPI`. If you're uncertain, please reach out via Twitter or email, and we can help work through it with you.
If you are creating something that works with or depends upon the OAS, you may decide you would like to use `OpenAPI` in the name of said thing. In these cases, it is important to consider whether your audience might confuse your effort as being under the auspices of the OAI. Ask yourself, "Might someone think this was an official tool/project/group of the OAI?" If the answer is, "Maybe," then consider adding a modifier. For example, `OpenAPI Tools` vs `OpenAPI-based Tools` or even `Tools for OpenAPI`. If you're uncertain, please reach out via Twitter or email, and we can help work through it with you.

Similarly, you may wish to have a graphic that uses the colors or visual themes of the OpenAPI logo. Again, tread carefully, as it is important for the community that the OAI maintain a strong, recognizable brand. For example, if you're considering using the barbell element or the segmented circle, you may want to reach out to the OAI proactively to avoid a rebranding exercise later.

## References to Teams in the Project

As per the charter, the OpenAPI Initiative (OAI) provides an open source, technical community, within which industry participants may contribute to building a vendor-neutral, portable, and open specification for providing technical metadata for REST APIs — the OpenAPI Specification (OAS). The following named groups may be properly referred to as:
Per the charter, the OAI provides an open source, technical community, within which industry participants may contribute to building a vendor-neutral, portable, and open specification for providing technical metadata for REST APIs — the OAS. The following named groups may be properly referred to as:

* **Business Governance Board** ("BGB", second reference)

* Comprised of official corporate entities (companies, schools, non-profits, etc.) who have signed the official project membership agreement to be members of the OpenAPI Initiative and are bound by the laws governed by the project’s charter. [[Read more here](https://www.openapis.org/participate/how-to-contribute/governance#BGB)]
* The Business Governance Board (BGB) consists of official corporate entities (companies, schools, non-profits, etc.) who have signed the official project membership agreement to be members of the OAI and are bound by the laws governed by the project’s charter. [[Read more here](https://www.openapis.org/participate/how-to-contribute/governance#BGB)]

* **Technical Steering Committee** ("TSC", second reference)

* The Technical Steering Committee (TSC) is open to any developer, end user or subject matter expert that participates in the activities of OAI, regardless of whether the participant is employed by an OAI member company. Influence on the evolution of the OAS comes by engaging with the TSC in technical discussions and by contributing to the project. [[Read more here](https://www.openapis.org/participate/how-to-contribute/governance#TDC)]
* The Technical Steering Committee (TSC) is open to any developer, end user, or subject matter expert that participates in the activities of OAI, regardless of whether the participant is employed by an OAI member company. Influence on the evolution of the OAS comes by engaging with the TSC in technical discussions and by contributing to the project. [[Read more here](https://www.openapis.org/participate/how-to-contribute/governance#TDC)]
* The OAI board approved a name change of this body from the Technical Developer Community to the Technical Steering Committee as of Feb. 8, 2018.

* **Technical Oversight Board** ("TOB", second reference)

* The Technical Oversight Board (TOB) is responsible for managing conflicts, violations of procedures or guidelines and any cross-project or high-level issues that cannot be resolved in the TSC for the Specification. The TOB shall also be responsible for adding, removing or re-organizing OAI Projects. The TOB shall not dictate or interfere with the day-to-day work of individual OAI Projects or their decisions. [[Read more here](https://www.openapis.org/participate/how-to-contribute/governance#TOB)]
* The Technical Oversight Board (TOB) is responsible for managing conflicts, violations of procedures or guidelines, and any cross-project or high-level issues that cannot be resolved in the TSC for the Specification. The TOB shall also be responsible for adding, removing or re-organizing OAI Projects. The TOB shall not dictate or interfere with the day-to-day work of individual OAI Projects or their decisions. [[Read more here](https://www.openapis.org/participate/how-to-contribute/governance#TOB)]

## Linux Foundation
## The Linux Foundation&reg;

The OpenAPI Initiative is one of the Linux Foundation's Collaborative Projects, which are independently funded software projects that harness the power of collaborative development to fuel innovation across industries and ecosystems.
The OAI is one of The Linux Foundation's Collaborative Projects.

* What is a Linux Foundation Collaborative Project?

* Collaborative Projects are independently funded software projects that harness the power of collaborative development to fuel innovation across industries and ecosystems. By spreading the collaborative DNA of the largest collaborative software development project in history, The Linux Foundation provides the essential collaborative and organizational framework so project hosts can focus on innovation and results. Linux Foundation Collaborative Projects span the enterprise, mobile, embedded and life sciences markets and are backed by many of the largest names in technology. For more information about Linux Foundation Collaborative Projects, please visit: [[Read more here](http://collabprojects.linuxfoundation.org/)]
* Linux Foundation Collaborative Projects are independently funded software projects that harness the power of collaborative development to fuel innovation across industries and ecosystems. By spreading the collaborative DNA of the largest collaborative software development project in history, The Linux Foundation provides the essential collaborative and organizational framework so project hosts can focus on innovation and results. Linux Foundation Collaborative Projects span the enterprise, mobile, embedded and life sciences markets and are backed by many of the largest names in technology. For more information about Linux Foundation Collaborative Projects, please visit: [[Read more here](http://collabprojects.linuxfoundation.org/)]

* What is the Linux Foundation?
* What is The Linux Foundation?

* The Linux Foundation is a nonprofit consortium dedicated to fostering the growth of Linux and collaborative software development. Founded in 2000, the organization sponsors the work of Linux creator Linus Torvalds and promotes, protects and advances the Linux operating system and collaborative software development by marshaling the resources of its members and the open source community. The Linux Foundation provides a neutral forum for collaboration and education by hosting Collaborative Projects, Linux conferences including LinuxCon, and generating original research and content that advances the understanding of Linux and collaborative software development. More information can be found at [[Read more here](http://www.linuxfoundation.org)].

### Graphics

This repository contains color (Pantone), black, and white versions of [the OpenAPI Initiative's logo](./graphics/) in both vector and bitmap. Whenever possible, prefer the color logo, though white or black treatments may be considered more appropriate under certain conditions, and the lettering may be omitted where a purely graphical representation is required. The OpenAPI logo should not be deformed or used in a way that may be considered disrespectful.
This repository contains color (Pantone), black, and white versions of [the OAI's logo](./graphics/) in both vector and bitmap. Whenever possible, prefer the color logo, though white or black treatments may be considered more appropriate under certain conditions, and the lettering may be omitted where a purely graphical representation is required. The OpenAPI logo should not be deformed or used in a way that may be considered disrespectful.

The [official Pantone swatches](./graphics/Pantone%20Color%20Swatches.pdf) are also available for reference.

## A Short History of the OpenAPI Initiative and the OpenAPI Specification

On [Nov. 5, 2015](https://www.linuxfoundation.org/news-media/announcements/2015/11/new-collaborative-project-extend-swagger-specification-building), SmartBear in conjunction with 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet announced the formation of the OpenAPI Initiative, an open source project under the Linux Foundation. As part of the formation of the OAI, SmartBear donated the Swagger specification to the Linux Foundation, meaning that the OpenAPI Specification is semantically identical to the specification formerly known as the Swagger 2.0 specification. It is widely recognized as the most popular open source framework for defining and creating RESTful APIs, and today tens of thousands of developers are building thousands of open source repos of tools leveraging the OpenAPI Specification. In 2010, the Swagger specification was created by Wordnik, who published it under an open source license one year later. In March of 2015, SmartBear acquired Wordnik's interests in the Swagger projects from its parent company, Reverb Technologies.
On [Nov. 5, 2015](https://www.linuxfoundation.org/news-media/announcements/2015/11/new-collaborative-project-extend-swagger-specification-building), SmartBear in conjunction with 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet announced the formation of the OpenAPI Initiative, an open source project under The Linux Foundation. As part of the formation of the OAI, SmartBear donated the Swagger specification to The Linux Foundation, meaning that the OpenAPI Specification is semantically identical to the specification formerly known as the Swagger 2.0 specification. It is widely recognized as the most popular open source framework for defining and creating RESTful APIs, and today tens of thousands of developers are building thousands of open source repos of tools leveraging the OpenAPI Specification. In 2010, the Swagger specification was created by Wordnik, who published it under an open source license one year later. In March of 2015, SmartBear acquired Wordnik's interests in the Swagger projects from its parent company, Reverb Technologies.