OpenTelemetry Specification: the document your SDK has to pass

A specification repository with no code to install

Nothing in this repository runs. Its stated job is narrow and it states it plainly: the specification describes the cross-language requirements and expectations for all OpenTelemetry implementations. What you get when you clone it is prose, schema files and linting configuration. The primary language is recorded as Makefile, which is a fair summary of the build, but the Makefile drives spell checking, text linting, link checking and cspell over Markdown. It does not compile a binary and it is not a dependency you add to a pom.xml or a package.json.

That makes the audience narrow in a useful way. The people who need this repository are the ones writing an SDK, the ones reviewing a vendor claim of conformance, and the engineers deciding whether the telemetry their platform emits will survive a change of language or vendor. The people who want to emit a span today should read the specification for the requirement and then reach for the language SDK, which the repository does not contain.

The repository names its own homepage at opentelemetry.io and the specification is published separately from the source. The README points at the published copy hosted at opentelemetry.io/docs/specs/otel as the current text, and keeps the Markdown sources under the specification directory. So there are two artifacts, and they are not always the same age. Someone reading a vendor's claim is usually reading a published page, while anyone arguing about what the requirement actually says needs the Markdown.

Semantic Versioning is what makes the document quotable

The clause that does the most work is short: changes to the specification are versioned according to Semantic Versioning 2.0 and described in CHANGELOG.md, while layout changes are not versioned. Specific implementations of the specification should specify which version they implement. Three consequences follow.

First, you can pin. If your collector or SDK names the specification version it implements, the requirements text at that tag is what it was measured against, and reformatting a heading will not break your pin because layout is excluded from versioning. Second, you can audit. That file records what moved between tags, which matters when an upgrade changes a behaviour you depended on.

Third, and this is the part people skip, the requirement is that an implementation state the version it implements rather than the version that happens to be newest. A vendor claiming conformance to the newest tag is making a stronger claim than one pinning an older tag, and the specification deliberately does not conflate them. When you compare two SDKs, ask for the pinned version first.

There is an unfinished edge here worth naming. The README says changes to the change process itself are not currently versioned but may be independently versioned in the future. So the governance rules that decide what enters the document are themselves outside the versioning discipline applied to the content.

Contributions move through approvers, triagers and a Tuesday meeting

This is a document produced by a process, and the process is described closely enough to plan against. New specification text enters through a pull request, and the README routes every submitter to the section of CONTRIBUTING.md titled Proposing a change before opening one. Reading that section first is not optional courtesy; it is the first gate on the change itself.

Roles are separated rather than blurred. Triagers come from the OpenTelemetry Governance Committee. Approvers are specification sponsors and a named list of individuals with their employers, spanning Grafana Labs, Dynatrace, Microsoft, Oracle, Splunk, OllyGarden, MyDecisiveAI and an independent seat. Maintainers are a superset of the Technical Committee, currently Josh Suereth at Google and Robert Pająk at Splunk. Emeritus approvers stay listed by name, which tells you the project tracks departures rather than rewriting its history.

Questions have a stated route rather than a forum. Slack goes to the #otel-specification channel, and a CNCF account must be created first. Anything needing more attention goes to the specifications meeting, which is held every Tuesday at 8 AM Pacific in a European and US friendly slot, with notes kept in a linked Google doc. APAC friendly meetings happen on request. Escalation to the technical committee is by email, per the community repository's mailing lists page, and the technical committee keeps its own meeting notes.

The practical consequence for a reader outside the project: expect the pace of a standards body. A requirement you want will not appear on a feature request.

Running the repository's own checks instead of trusting a markdown preview

There is no install step because there is no package to install. The README does not document a build or a deployment. What it does ship is the tooling that keeps the text honest, wired into a Makefile at the repository root. Python and pip are detected at the top of the Makefile, and a check-python target exits with an error message if either is missing.

The default target chains the whole lint suite:

all: install-tools markdownlint textlint markdown-link-check cspell

That is the single entry point for checking a change locally before opening a pull request. The cspell and textlint stages install the Node dependencies when they are not already present, running npm ci --ignore-scripts first.

Spell checking is a separate target and is the fastest signal to run on its own:

cspell:
	@if ! npm ls cspell; then npm ci --ignore-scripts; fi
	npx cspell . --no-progress

Two details in the repository are easy to miss and both cause real failures. The cspell stage runs over the whole tree, not just the specification directory, so a misspelled name anywhere in the sources blocks the run. And the Makefile pins SEMCONVGEN_VERSION=0.17.0 for semantic conventions, with a comment pointing at open-telemetry/build-tools for updates, and a warning that the links in semantic_conventions/README.md and .vscode/settings.json must be kept in sync by hand.

One stage does not need local Node at all. Link checking runs inside a pinned container:

docker run --rm \
		--mount 'type=bind,source=$(PWD),target=/home/repo' \
		lycheeverse/lychee:sha-8222559@sha256:6f49010cc46543af3b765f19d5319c0cdd4e8415d7596e1b401d5b4cec29c799

That image is pinned by digest, not by a moving tag. If you are offline, this is the stage that fails, and the failure is about your environment rather than about the prose.

An OTEP is the unit of change, and schemas sit beside the prose

The top level tree tells you how a change arrives and where its machine-readable form lives. Alongside the specification directory sit oteps/, schemas/, supplementary-guidelines/, internal/ and development/. An OTEP is the authored proposal a change is worked out in before any of it becomes normative text.

Two more entries are worth knowing about. RELEASING.md sits at the root, so how a version gets cut is written down rather than tribal. And AGENTS.md and CLAUDE.md are present alongside it, which tells you the repository carries instructions aimed at automated coding assistants, not just human contributors.

The compliance matrix is the only answer to is this SDK conformant

The repository ships spec-compliance-matrix.md, described in the README as the compliance of implementations with specification. That file, not the prose, is what settles a vendor question. A matrix that lists an implementation tells you the project maintainers have a place to record what that implementation does against the requirements.

A spec-compliance-matrix/ directory sits alongside the single markdown file of the same name.

Notice what the matrix cannot do. It records conformance claims against a specification version; it does not tell you whether a given collector build, a given exporter or a given environment variable combination was configured correctly at runtime. Conformance is a statement about the implementation, not about the deployment.

Project status and notable past milestones are tracked off repository, on a project page at opentelemetry.io/status/. Work in progress is tracked on the repository's own milestones page. So the question is never whether the specification is alive, but which milestone a requirement you care about sits in.

Where this document loses to a language SDK or a collector build

The honest limitation is that this repository is the wrong tool for most day-to-day work. Emitting a trace does not require reading the specification. A language SDK implements it, and the SDK, not the specification, is what you put in a dependency file. Reaching for this repository to answer how to set an exporter attribute is a detour through a document written for implementers.

The second limitation is timing. Every requirement you depend on can move. Releases arrive every five to six weeks in the repository's release history: v1.60.0 on 2026-08-07, v1.61.0 on 2026-09-14 and v1.62.0 on 2026-10-22, each one carrying whatever changed. Pinning a version protects you from breaking changes, and it also means you are reading a document that is no longer the newest one, which is a deliberate trade the specification makes on your behalf.

A third gap is documentation scope. The README does not document how a specific language implementation should be tested against the matrix, does not give a conformance test suite in the top level tree, and does not name a rollback procedure for a requirement that turns out to be wrong. If you are a vendor, those gaps are yours to fill.

On the alternative axis, an implementation-first project such as a language SDK inverts the relationship entirely. It ships code, pins its own version, and encodes the requirement as behaviour you can read in the source. The specification inverts it: no behaviour at all, only the normative text both the code and any competing code are measured against. Teams with one language and one vendor get nothing from the document. Teams that evaluate or reimplement telemetry get most of it.

Editorial conclusion

Adopt it as the reference when you are choosing between SDKs, writing a collector or reimplementing telemetry in a second language, and skip it if you only want to emit one span today, since the language SDK packages cover that on their own. It carries no runnable code, so it cannot be installed, and its requirements move with each release, roughly every five to six weeks, so reading it once and acting months later is how teams end up coding against a requirement that has since shifted. Verify first that the implementation you intend to run has a row in spec-compliance-matrix.md and that the row names the specification version the vendor pins, because an implementation with no row tells you nothing about conformance and an unpinned claim tells you nothing either.

Frequently asked questions

Official sources

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