Semantic Versioning

Increment the MAJOR version when you make incompatible API changes.

• A breaking change requires consumers to modify their integration code.
• Examples: removing a field, renaming an endpoint, changing a data type.
• A major version bump signals that backward compatibility is broken.
• In schema evolution, a new MAJOR version indicates the new schema cannot read data written by the old schema.

Increment the MINOR version when you add functionality in a backward-compatible manner.

• New optional fields, endpoints, or features are added without breaking existing consumers.
• Existing functionality continues to operate unchanged.
• In a content model, adding a new optional property to a JSON Schema is a MINOR change.
• Consumers can safely upgrade without modifying their code.

Increment the PATCH version when you make backward-compatible bug fixes.

• Corrects incorrect behavior without altering the public API.
• Examples: fixing a validation rule, correcting a typo in a description, resolving a calculation error.
• Consumers should always be able to accept PATCH updates without risk.
• A PATCH bump signals improved stability, not new capability.

SemVer supports optional pre-release and build metadata labels appended with a hyphen or plus sign.

• 1.0.0-alpha.1 indicates an unstable pre-release version.
• 1.0.0+build.2024 adds build metadata without affecting precedence.
• Pre-release versions have lower precedence than the associated normal version.
• Useful for continuous integration pipelines and staged rollouts of schema changes.

SemVer defines a strict ordering algorithm for comparing versions.

• Precedence is calculated by comparing MAJOR, MINOR, PATCH, and pre-release identifiers numerically from left to right.
• 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.
• 1.0.0-alpha < 1.0.0.
• This deterministic ordering is critical for dependency resolvers in package managers and schema registries.

In schema-driven content modeling, SemVer maps directly to compatibility guarantees.

• MAJOR: A schema change that breaks backward or forward compatibility.
• MINOR: Adding an optional field; forward-compatible, backward-compatible.
• PATCH: Correcting a description or constraint without altering data structure.
• A Schema Registry enforces these rules, rejecting incompatible schema versions before they reach production.

A guarantee that consumers using an older schema can process data produced by a newer schema without error. In SemVer, this corresponds to a MINOR or PATCH version bump. New fields must have default values, and no existing fields can be removed or have their types changed. This is the most critical compatibility type for APIs and event-driven architectures where producers upgrade before consumers.

A guarantee that consumers using a newer schema can process data produced by an older schema. This is harder to achieve and requires careful design: schemas must ignore unknown fields rather than failing, and all new fields must be optional from the start. In data pipelines, forward compatibility allows consumers to be upgraded independently of producers, a key requirement for rolling deployments in distributed systems.

The process of modifying a data schema over time while maintaining compatibility guarantees. Evolution strategies include:

• Adding optional fields (safe, backward-compatible)
• Removing fields with defaults (safe, forward-compatible)
• Renaming fields (breaking, requires a MAJOR bump)
• Changing data types (breaking, requires a MAJOR bump) SemVer provides the communication protocol for signaling the impact of each evolution step to downstream consumers.

An explicit agreement between a data producer and its consumers that defines the schema, semantics, and quality guarantees of exchanged data. A data contract typically includes:

• A versioned schema reference
• Semantic meaning of each field
• Service Level Objectives (SLOs) for freshness and completeness
• Ownership and contact information SemVer is the versioning backbone of data contracts, enabling automated enforcement of compatibility rules in CI/CD pipelines.