OAI/OpenAPI-Specification: the Markdown source of truth for HTTP API descriptions
The OpenAPI Specification Repository
At a glance
- What is it?
- This repository is the specification itself, not a parser or a code generator. It holds the Markdown sources for every published OpenAPI version, and its value depends on which OAS version your tooling already supports.
- Who is it for?
- Adopt this repository as a reference and as the upstream source for spec text, not as a runtime dependency. If you are choosing an OAS version for a new API, read the version directory for that release and confirm your generators and validators support it before writing a single path item; the gap between 3.1.x and 3.2.x in the release list is where tooling mismatches surface.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Markdown, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What this repository is, and what it deliberately is not
The README describes the OpenAPI Specification as a standard, programming language-agnostic interface description for HTTP APIs, maintained within the OpenAPI Initiative, a Linux Foundation Collaborative Project. That sentence defines the artifact: a document format, expressed in YAML or JSON, that describes what an HTTP service exposes. It is not a library you import and not a server you start. The repository holds the Markdown sources for all published specification versions, with the rendered, authoritative HTML published separately at spec.openapis.org. If you arrived looking for a parser, a mock server, or a client generator, you are in the wrong repository. The README points to a separate list of implementations for that.
The scope limits are stated plainly. The specification does not require rewriting existing APIs, and the described service may not even be owned by the person who wrote the description. It also does not mandate a development process, so design-first and code-first workflows are both permitted. The README is explicit that not all services can be described by OpenAPI, and that the format is not intended to cover every possible style of HTTP API, though it includes support for REST APIs. That last admission matters more than it usually gets credit for: if your interface is event-driven, streaming, or RPC-shaped, the specification may not be the right description language, and no amount of schema work will fix a mismatch in the underlying interaction model.
Who the specification is written for
The README lists three machine-readable use cases: interactive documentation, code generation for documentation, clients and servers, and automation of test cases. Each maps to a different reader. Documentation tooling consumes the document to render a browsable reference. Generators consume it to emit client libraries or server stubs. Test automation consumes it to derive request and response cases. The common requirement is that the description be complete enough that a consumer can interact with the service with minimal implementation logic, without reading source code, extra documentation, or captured network traffic.
A second audience is the specification's own contributors. The repository is community-driven, and the README describes the development process as guided by a Technical Steering Committee, with weekly web conferences to review open pull requests and discuss open issues. Participation in those calls is open. If you are evaluating this repository because you want to influence the format rather than consume it, the entry points are the contributing guidelines, the discussions, and the issue tracker, and the README warns that not all feedback can be accommodated. For most engineering teams, the practical audience is narrower: whoever owns the API contract and whoever owns the generators that read it.
How versions and releases are organized in the repository
The layout is version-first. The README states that the repository contains the Markdown sources for all published OpenAPI Specification versions under a versions directory, and that the authoritative HTML renderings live at spec.openapis.org. Release notes and release candidate versions live on the GitHub releases page rather than in the version directories. The supplied release list shows 3.2.1 dated 2026-09-10, 3.2.0 dated 2025-09-19, and 3.1.2 dated 2025-09-19. Note the shape of that list: a patch release for 3.2 arrived roughly a year after 3.2.0, and a 3.1 patch landed the same day as 3.2.0. Patch releases on older minor lines do happen, so a team pinned to 3.1.x is not automatically stranded.
The README also describes a branch model for work in progress. Development of the next version is performed as features merged into a working branch, and upon release that branch is merged to main. That means main is not a stable reference for unreleased behavior. If you need the text of a published version, take it from the version directory or from the rendered HTML, not from main.
Getting the sources and validating the Markdown
There is nothing to install and no runtime to configure. The README's own framing is that this project is the starting point for OpenAPI, where you find information about the specification, simple examples, and general project information. The concrete actions it names are reading the Markdown sources in the versions directory, reading the rendered HTML at spec.openapis.org, and consulting the examples linked from learn.openapis.org. A clone is the whole setup:
git clone https://github.com/OAI/OpenAPI-Specification.git
What you can run locally is the Markdown validation that gates contributions. The README carries a validate-markdown workflow badge, and it states that build, test, schema publication, and release command infrastructure is shared with other OpenAPI Initiative specification repositories through OAI/build-infra. The README directs readers to that repository's README and CONTRIBUTING guide for details on the shared tooling. It does not spell out the individual commands in this file, so treat the exact invocation as something to confirm in OAI/build-infra before you rely on it. There is no config key documented here for the specification itself; the only configuration surface described is the contribution and build tooling owned by the shared infrastructure repository. If you are consuming the spec rather than editing it, your real configuration lives in whichever generator or validator you chose, not here.
Where the specification stops being the right tool
The README concedes that not all services can be described by OpenAPI and that the format is not intended to cover every possible style of HTTP API. That is a real boundary, not boilerplate. A service whose interface is primarily a long-lived bidirectional stream, or whose contract is defined by a queue and message schema rather than request and response pairs, will fight the document structure. You can often force a description into shape, but the resulting document describes something adjacent to what the service actually does, and every generator downstream inherits that distortion.
The second limitation is organizational rather than technical. The specification does not require binding any software to a service, and the described service may not be owned by the creator of its description. That is a feature for third-party description, and a hazard for accuracy: a hand-written document can drift from the service it claims to describe, and nothing in the specification prevents that. The document is a claim about an interface, not a verified contract. If your process has no step that checks the description against the running service, the specification's guarantees about discoverability apply to a document that may no longer be true.
A third constraint is version support in the surrounding ecosystem. The repository publishes the text of each version; it does not publish the generators, validators, or documentation renderers that read it. A newly released minor version can be fully specified here while the tools your team depends on still target the previous one. The release timeline in the supplied list, with 3.2.0 and a 3.1 patch arriving on the same day, is a reminder that the specification project maintains more than one line at once, and your tooling may be tracking a different line than your documents.
What the alternative looks like: describing APIs with code or schema-only formats
The nearest alternative in practice is not another specification repository but a different description strategy: generating the contract from annotated source code, or describing the payloads with a schema language alone. The difference is in what the artifact can express. A schema language describes the shape of data. The OpenAPI Specification describes an HTTP interface: the operations, the paths, the parameters, the request and response bodies, and the metadata that lets a consumer call the service with minimal implementation logic. If your problem is validating a JSON payload, a schema is a smaller and more direct answer. If your problem is letting someone generate a client without reading your source, the schema alone will not carry the operations and their wiring.
The README addresses the code-first versus design-first question directly, and it declines to pick a side: the specification does not mandate a specific development process, and the README states that it facilitates either technique by establishing clear interactions with an HTTP API. That neutrality is the honest position, and it also means the repository will not resolve your process argument. Choosing between the two is a decision about where the contract lives and who is allowed to change it, and that decision is yours to make outside this repository.
Maintenance cost and licence implications
For consumers, the maintenance cost is close to zero at the repository level. You do not upgrade a dependency, because you do not depend on this code. What you do maintain is your choice of specification version and the tooling that reads it, and those move on their own schedules. The repository's own maintenance is visible in the release list: a minor release in September 2025, patch releases on two lines, and a 3.2.1 patch in September 2026. If you pin documents to a version, budget for the migration work when you move to the next minor line, because your generators and validators have to move with you.
On licensing, the README links to the repository licence and the supplied metadata identifies it as Apache-2.0. Apache-2.0 is a permissive licence that typically allows use, modification, and redistribution with the conditions the licence text specifies, including its notice and attribution requirements. This is a description of the licence family, not legal advice. If you are redistributing the specification text, embedding it in a product, or building a derivative specification, read the LICENSE file in the repository and the rendered version at spec.openapis.org, which the README notes includes full credits and citations, and take your own counsel on what your distribution requires.
Editorial conclusion
Adopt this repository as a reference and as the upstream source for spec text, not as a runtime dependency. If you are choosing an OAS version for a new API, read the version directory for that release and confirm your generators and validators support it before writing a single path item; the gap between 3.1.x and 3.2.x in the release list is where tooling mismatches surface.
Community notes