OpenTelemetry Specification: What the Repo Actually Defines, and How to Build It Locally

The contract behind every OpenTelemetry SDK, not a library you import

The README opens with the scope in one line: the OpenTelemetry specification "describes the cross-language requirements and expectations for all OpenTelemetry implementations." That sentence is the whole product. This repository does not ship a tracer, an exporter or a collector binary. It ships the prose that SDK authors in Go, Java, Python, JavaScript and the rest are expected to satisfy, plus the process for changing that prose.

The audience follows from that. If you are choosing an observability backend, this repository will not help you. If you are implementing an SDK, reviewing a vendor's claim that it is "OpenTelemetry compliant", or writing semantic conventions for a domain that OpenTelemetry has not covered yet, the normative text is the thing you cite. The related searches around "OpenTelemetry span" and "OpenTelemetry grpc" point at concrete concepts the specification defines, but the definition lives here and the working code lives in the per-language repositories.

There is a second audience that is easy to miss: platform teams that need to argue about behaviour. When two SDKs disagree about how a span status is set, the specification is the tiebreaker, and the compliance matrix is the evidence about which implementation is behind.

How the repository is laid out and how a change reaches the spec

The top-level entries tell you most of the architecture. The normative text sits under specification/, with supplementary material under supplementary-guidelines/ and the enhancement proposals under oteps/. Semantic convention work has its own schemas/ directory, and spec-compliance-matrix.md plus the spec-compliance-matrix/ directory record how far each language has got against the requirements.

Versioning is explicit. The README states that changes to the specification are versioned according to Semantic Versioning 2.0 and described in CHANGELOG.md, and that specific implementations should state which version they implement. That last clause matters more than it looks: it means a vendor claiming support for OpenTelemetry is expected to name a spec version, and you can check that version against the changelog.

The change process is documented rather than implied. CONTRIBUTING.md carries a "Proposing a change" section that the README tells contributors to read before opening a pull request, and questions that need more attention go to the regular specifications meeting, held every Tuesday at 8 AM Pacific time, with APAC-friendly meetings on request. Escalation to the technical committee runs over the project mailing lists. That is a slower path than a normal library pull request, and it is deliberate: a merged change here propagates into every SDK.

Building the specification locally with make and the Node toolchain

The repository is Markdown plus a Makefile, so "installing" means preparing the tooling that lints and checks the text. The Makefile detects python3 or python and pip3 or pip, and the check-python target fails with an explicit message if either is missing. The default all target chains install-tools, markdownlint, textlint, markdown-link-check and cspell, so a single command runs the full check suite:

make all

If you only care about language, there is a narrower target. The Makefile defines language-analysis as textlint plus cspell, and both targets install their npm dependencies on demand when the package is not already present:

make language-analysis

Textlint can also rewrite files rather than just report on them. The Makefile provides textlint-correction, which runs npx textlint --fix . after ensuring the dependency is installed. Treat that as a review step, not a save hook, because it edits prose in place.

make textlint-correction

Link checking is the one target that is not pure Node. markdown-link-check shells out to a pinned lychee container image, mounting the working directory into /home/repo and passing .lychee.toml as the config, with fragment checking enabled. That means Docker has to be available for that target, and the Makefile comment notes that yamllint is deliberately not part of all yet because of Mac behaviour. The README itself gives no install instructions beyond pointing at the repository, so the Makefile is the real entry point.

The compliance matrix is the part application teams should read first

A specification that describes cross-language requirements has an obvious failure mode: the requirement exists, the SDK does not implement it. The repository addresses this with spec-compliance-matrix.md and the spec-compliance-matrix/ directory, which the README links under the heading "Specification compliance matrix by language".

This is the section most likely to save an application team a wasted afternoon. If you are planning to rely on a specific behaviour, the matrix tells you whether the language you deploy in has it. The specification being normative does not make the behaviour available in your runtime, and a gap in one SDK is not a defect in the document. It is simply the state of implementation.

Read the matrix before the specification, not after. Working the other way around produces the common complaint that OpenTelemetry documentation is inconsistent, when the actual situation is that the prose is uniform and the implementations are not.

Where the specification is the wrong tool

The repository is not a tutorial and does not try to be. There is no quickstart, no sample application, and no explanation of how to instrument a service. Anyone arriving from a search for how to use OpenTelemetry will find a normative document and a contribution process, and will need the language-specific SDK documentation instead.

It is also the wrong place to look for stability guarantees about a specific SDK version. The README notes that implementations should specify which version they implement, but that is a statement about what implementations ought to do, not a promise that any given release tracks the latest spec. A vendor can be several spec versions behind and still be internally consistent.

The development process is another constraint. Changes go through the Tuesday specification meeting and, when needed, escalation to the technical committee. If your team needs a behaviour fixed quickly, this repository is the wrong lever; the fix has to land in the SDK you actually run. The specification moves at the pace of consensus across many vendors, and the README's meeting cadence is a fair signal of that pace.

Finally, the source of truth for readers is split. The README says the latest release is hosted at opentelemetry.io/docs/specs/otel, while the Markdown under specification/ is the working source. If you need to cite a stable version, cite the release and its version number, not the main branch.

OpenTelemetry versus a vendor's own telemetry schema

The obvious alternative to a cross-language specification is a single vendor's instrumentation format, where one company owns the schema, the SDKs and the backend. The difference is not quality, it is where the coupling sits. A vendor schema can change a field name and ship the change across its own stack in one release; the OpenTelemetry specification has to carry that change through a contribution process, a semantic convention update, and then independent implementations in every supported language.

The trade is real in both directions. A vendor format gives you a coherent, fast-moving target and a single support contact. The specification gives you the ability to switch backends, or run several at once, without re-instrumenting, which is the reason the project exists. The cost is that you inherit the specification's release cadence and the compliance gaps of whichever SDK you chose.

A second alternative is to instrument directly against one SDK's API and ignore the specification entirely. That works until you need a second language, a second backend, or a vendor that implements the spec slightly differently. The specification is the layer that makes those moves cheap, and it is worth the reading time only if you expect to make them.

Maintenance, release cadence and the Apache 2.0 licence

The repository is not archived, and the last push was on 2026-08-07, which is the same timestamp as the v1.60.0 release. The two preceding releases, v1.59.0 and v1.58.0, landed on 2026-07-10 and 2026-06-22, so the project has been cutting releases roughly monthly through the middle of 2026. For a specification, that is a fast cadence, and it means the changelog is worth reading before you pin a version in a conformance test.

Upgrade cost is mostly reading cost. Because the specification is versioned under Semantic Versioning 2.0 and described in CHANGELOG.md, you can diff the changelog between the version you target and the current one rather than re-reading the whole document. Layout changes are explicitly not versioned, so a reorganisation of the Markdown files is not a signal that requirements changed.

Licensing is straightforward: the README states that contributions are licensed under the Apache 2.0 License, and the repository carries a LICENSE file. That permits commercial use and modification, and it does not require you to open source your own implementation. It also means there is no separate commercial edition or licence key to negotiate. This is a statement about what the repository says, not legal advice; if you are embedding specification text in a product, have counsel read the LICENSE file rather than this paragraph.

Editorial conclusion

Adopt the specification repository if you are writing an SDK, a collector distribution, a semantic convention or a conformance test, and you need the normative text rather than a vendor's summary. Do not adopt it as a getting-started guide: the README points readers to opentelemetry.io/docs/specs/otel for the latest release, and the Markdown sources under specification/ are the working draft. Before you rely on any single clause, check spec-compliance-matrix.md for the language you use, because the README states that this matrix tracks compliance of implementations with the specification, and a requirement that one SDK has not implemented is not a requirement you can count on at runtime.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes