The OpenAPI Specification builds itself from another repository's main branch

The one dependency is a git reference to another main branch

The manifest has a single runtime dependency and it is not a package. It is a git address pointing at the shared build infrastructure repository, pinned to that repository's main branch rather than to a tag or a commit. The front page says the same thing in prose: build, test, schema publication and release commands are shared with the other OpenAPI Initiative specification repositories through a separate build infrastructure project. Every script in the manifest is a thin wrapper around a command from that package, so the logic that turns Markdown into a published specification does not live in this repository at all. The consequence is straightforward and worth stating before you build anything: a change in the other repository can change your build without a commit here unless yarn.lock pins it.

The Node range is a single major, and the package version is a placeholder

The manifest declares a Node engine range of at least 24 and below 25, which is a narrower constraint than most projects state, and it pins the package manager to a specific major and minor of Yarn. There is also a node version file at the root, so the version is expressed in two places. The version field of the package itself is zero point zero point zero, and its name is an infrastructure name rather than a specification name, which means nothing in the manifest tells you which version of the specification a branch targets. That information lives in the versions directory, where the Markdown sources for each published version sit, and in the branch name. So a contributor arriving on the wrong Node major is turned away by the manifest, while a contributor wanting to know which specification they are editing has to read the tree.

Two Markdown linters and a link checker sit between a pull request and a release

Because the deliverable is prose, the tooling is mostly about prose. There is a repository level Markdown lint configuration and a separate one scoped to the specification itself, so the specification text and the surrounding documents are held to different rules. There is a specification configuration file that the build reads, a link checker configuration, a style guide, a test suite with its own runner configuration, and a scripts directory. The manifest exposes the two halves of that as commands, one that formats Markdown and one that validates it, and the source build runs validation before it builds and before it publishes schemas. The published artefact is also not the Markdown: the file asks contributors to review both the Markdown sources here and the authoritative HTML rendering hosted on the specification site, which is where readers actually read it.

The scope statement rules out whole families of HTTP API

One paragraph of the front page is about what the specification does not do, and it is more useful than the paragraph about what it does. It says the specification does not require rewriting existing APIs, and does not require binding any software to a service, adding that the described service may not even be owned by the creator of the description. It also says plainly that not all services can be described by OpenAPI, that the specification is not intended to cover every possible style of HTTP API, and that it does include support for REST. It does not mandate a development process, so neither design first nor code first is required, and the file's claim is that it facilitates either. For a reader, the consequence is that a description of a service you do not own is legitimate, and so is the fact that an unusual API shape may be out of scope.

Two releases of the 3.2 line landed a year apart

The release history is short and irregular. Version 3.1.2 and version 3.2.0 were both published on 2025-09-19, about half an hour apart, with release titles that announce the version. The next entry is version 3.2.1, published on 2026-09-10, so a patch release on the same minor line arrived almost a year after the minor release itself. The last push to the main branch is dated 2026-10-04, about three weeks after that patch. What this tells a consumer is that the version number alone does not tell you how fresh a specification is, and that a minor line can sit unchanged for long stretches. It also tells a contributor that the release rhythm is not a schedule to plan against.

The next version is developed on a branch that is merged into main at release

The governance section explains the shape of the work. A Technical Steering Committee guides development of the next version, and the group of committers brings API expertise, incorporates community feedback and expands as appropriate. All development activity on the future specification is performed as features and merged into that development branch, and when the future version is released the branch is merged into main. The committee holds weekly web conferences to review open pull requests and discuss open issues, participation is open to the community, and the full meeting calendar is published. The root carries the corresponding documents: a maintainers file, a governance file, a technical oversight file, a security considerations file, and a file naming the special interest groups. So a clone of main is the last released specification, and the in-progress one is somewhere else.

The process tells you that your proposal may be declined

The participation section is unusually candid about the last step. It says not all feedback can be accommodated, and that there may be solid arguments for or against a change being appropriate for the specification. Before that, it lists what a contributor is expected to do: read the Markdown sources and the authoritative renderings including their credits, read the contributing process, check the discussions, issues and pull requests to see whether someone has already raised the idea, and create a discussion with clear explanations of related use cases. One recommendation stands out for what it tells you about how attention works here: subscribe to an open issue through a code triage service, one issue a day or a week. A proposals directory sits at the root, and special interest groups are named, so a large change has a documented path even though that path can end in a refusal.

Editorial conclusion

Use this repository if you are writing a description, checking what the current version says, or following how a community standard changes, because the sources, the style guide and the governance files are all here in the open. Do not assume the build is reproducible without checking, since the command infrastructure is tracked as a branch reference rather than a version, and check the published rendering as well as the Markdown before you rely on a wording, because the README calls the HTML renderings the authoritative source of truth.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. OAI/OpenAPI-Specification on GitHub
3. Project website
4. README
5. Releases