The OpenAPI Style Guide is a reference document that establishes correct terminology and naming conventions for referring to the OpenAPI Initiative, the OpenAPI Specification, and related projects and tools.
The guide addresses a practical problem: as the OpenAPI Specification has become mainstream, inconsistent naming and terminology create confusion in technical discussions, presentations, and community communications. The solution is straightforward—it provides explicit rules for how to name and reference the specification, the initiative, and derivative works. The guide distinguishes between the OpenAPI Specification itself, abbreviated as OAS after first mention, and the OpenAPI Initiative (OAI) that governs it, clarifying that these are separate entities. It also covers when to use shorthand forms like "OpenAPI" in comparative contexts and how to handle historical references to Swagger.
Anyone building tools or projects that depend on or work with the OpenAPI Specification should consult this guide before naming their work or creating associated branding. The guide is particularly relevant for developers creating tooling in the OpenAPI ecosystem who want to avoid implying official affiliation with the OpenAPI Initiative. It recommends adding modifiers to project names—such as "OpenAPI-based Tools" rather than simply "OpenAPI Tools"—when there is any risk of audience confusion about whether a project is officially maintained by the OAI. The guide also addresses visual branding, cautioning against reusing OpenAPI logo elements or color schemes without explicit coordination with the initiative.
The project functions as a living reference maintained by the OpenAPI Initiative to support consistent community communication. It provides guidance on referencing internal governance structures like the Business Governance Board and establishes clear escalation paths for contributors uncertain about naming decisions, directing them to reach out via Bluesky, Slack, or email for clarification.
