Schema Fundamentals

A telemetry schema is a versioned changelog that documents semantic-convention changes (renames, additions, deprecations) for telemetry signals. Each schema file records what changed and is stored under a predictable path such as /schema/version. Backends, processors, and collectors use the schema_url embedded in telemetry to interpret and transform incoming data correctly over time. Example schema file (YAML):

file_format: 1.1.0
schema_url: https://opentelemetry.io/schemas/1.1.0
versions:
  - version: 1.1.0
    changes:
      - rename_attributes:
          - from: http.status_code
            to: http.response.status_code

The schema_url within telemetry has two important parts:

family name (groups the logical set of schema versions)
semantic version (MAJOR.MINOR.PATCH)

If a schema host changes, the URL may redirect to a new location, allowing consumers to discover the rules for the referenced schema version.

The image illustrates the structure of schema URLs, showing how a base URL is combined with a family and version number. It also mentions the inclusion of redirects.

Embedding schema_url makes telemetry self-describing. Example telemetry JSON:

{
  "schema_url": "https://opentelemetry.io/schemas/1.1.0",
  "resource": {
    "service.name": "payment.service"
  }
}

Typical schema files list changes in order and can target scopes: all, spans, metrics, etc. Example schema with scoped changes:

schema_url: https://opentelemetry.io/schemas/1.1.0
versions:
  - version: 1.1.0
    all:
      rename_attributes:
        - from: http.status_code
          to: http.response.status_code
    spans:
      add_attributes:
        - key: telemetry.source
          value: "payment-service"
    metrics:
      remove_attributes:
        - key: deprecated.metric.id

Table: Schema scope mappings

Scope	Purpose	Example change
`all`	Applies to every signal (spans, metrics, logs)	`rename_attributes: {from: http.status_code, to: http.response.status_code}`
`spans`	Only affects span attributes	`add_attributes: [{key: telemetry.source, value: "payment-service"}]`
`metrics`	Only affects metric attributes	`remove_attributes: [{key: deprecated.metric.id}]`

Semantic versioning determines compatibility and consumer behavior. Follow SemVer rules: patch releases are ignorable structural fixes, minor versions add backward-compatible rules, and major versions introduce potentially breaking changes. Tools should read schema files up to the minor version they support; newer minors or different majors may contain rules they don’t understand.

The image outlines "SemVer Rules for Schemas," describing three versioning types: MAJOR for incompatible changes, MINOR for backward-compatible additions, and PATCH for ignorable additions. It also specifies consumer behavior for version changes.

Consumers can safely read schema files with the same major version and a minor version less than or equal to the minor they support. Patch differences are always safe.

Compatibility examples (quick reference):

File version	Consumer version	Compatible?	Notes
`1.1.0` vs `1.1.0`	`1.1.0`	Yes	Exact match
`1.0.1` vs `1.0.9`	`1.0.x`	Yes	Patch-only differences are compatible
file `1.1.x` vs consumer `1.3.x`	`1.x`	Yes	Newer consumer can read an older minor
file `1.3.x` vs consumer `1.1.x`	`1.x`	No	File minor newer than consumer — consumer is behind
file `2.0.0` vs consumer `1.x.y`	major differs	No	Breaking changes possible

Concrete example

An SDK emits spans and metrics with schema_url = https://opentelemetry.io/schemas/1.2.0. Each span contains deployment.environment = "prod".
In schema 1.1.0 the same attribute was named environment.
If the backend stores data using 1.1.0, incoming 1.2.0 telemetry must be transformed before storage so the backend remains consistent.

The image is a diagram of a schema-aware observability system showing the flow of telemetry data from a source through a backend to storage, with schema transformation and translation rules applied. It includes a transformation of "deployment.environment" to "environment" in the storage phase.

How translation preserves user experience

SDK emits telemetry using the new schema (1.2.0) and queries or dashboards are written against deployment.environment.
Storage uses environment with schema_url = 'https://opentelemetry.io/schemas/1.1.0'.
A schema-aware query layer rewrites user-facing queries to match storage semantics.

Example user query (written against 1.2.0):

SELECT * FROM Spans WHERE deployment.environment = 'prod';

Translated storage query (rewritten to backend schema):

SELECT * FROM Spans WHERE environment = 'prod' AND schema_url = 'https://opentelemetry.io/schemas/1.1.0';

Collector example (schema translation at the edge)

Developers configure their SDKs normally and emit spans/metrics under 1.2.0 (e.g., deployment.environment = "prod").
Telemetry is sent to an OpenTelemetry Collector instead of directly to the backend.
The Collector runs a schema-transform processor configured with a target schema_url (for example, https://opentelemetry.io/schemas/1.1.0).
The processor consults both the incoming 1.2.0 rules and the target 1.1.0 rules to determine renames and rewrites.
The Collector outputs telemetry where attribute names and the schema_url match the target 1.1.0 format, then forwards it to the backend.

Because the Collector performs translation before storage, the backend receives consistent, target-schema-compliant payloads and does not need to perform per-item rewrites. Summary

Schema files are versioned declarations of semantic changes (renames, additions, deprecations).
The telemetry schema_url makes data self-describing and enables correct interpretation across the pipeline.
Follow semantic versioning: patches are safe, minors are backward-compatible additions, majors may break.
Schema transforms (in the Collector or backend) map attributes between versions so storage and queries remain consistent across schema evolution.

Links and references

Watch Video

Schemas Why Schemas Matter

Schema Translation Rules by Signal Type