From a597520dcf784fdd3704d7216b5567025e1d7aaa Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Fri, 8 Jun 2018 11:54:13 -0700 Subject: [PATCH] Adding guidelines for use of name/logo in projects/tools - Corrected typo - Added advice for using OpenAPI logo and name in projects/tools/groups - Moved history to the end to focus on guidance of the usage first --- README.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e9f43f5..8e1f459 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,6 @@ How to (and how not to) refer to the OAI in meetups, interviews, casual conversations, the settling of bar bets, and for conference presentations. -## 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. - ## 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: @@ -20,10 +16,16 @@ In order to connect readers familiar with the former name of the specification i ## The Initiative Name and Usage -The **OpenAPI Initiative** refers to the organization that oversees the specification. It must contain ONE spaces 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. 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 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.* +## 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. + +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: @@ -58,3 +60,7 @@ The Open API Initiative is one of the Linux Foundation's Collaborative Projects, This repository contains color (Pantone), black, and white versions of [the Open API 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. 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.