Learn

Version Alignment

How Cuddler keeps schema versions, contract versions, and rendered outputs in lockstep.

Release discipline

What version alignment keeps in lockstep

Alignment is not only about one schema identifier. It is about keeping the whole public release family synchronized.

Contract identitySchema IDs and instance references

The canonical schema identity and the instance reference should describe the same exact version.

Working artifactsData, template, and examples

The practical files that authors use should all target that same version family.

Published surfacePages, routes, and bundles

The public URLs and downloadable artifacts should describe the same release readers think they are using.

When those three surfaces drift apart, version mismatch becomes a predictable failure mode.

Version alignment keeps a Cuddler document family from quietly drifting apart. The model is simple: the schema version, the contract version, and the generated artifacts should stay in lockstep so readers and tools know exactly what they are looking at.

What alignment means

  • The schema identity should match the canonical published identity for that version.
  • The data and template artifacts should refer to the same version family.
  • A newer version should be introduced deliberately, not accidentally.

Why it matters

Without alignment, it becomes easy to mix a newer schema with an older example or a template that was written for a different rule set. That kind of mismatch creates avoidable debugging work and weakens trust in the final document.

Practical habit

When you change a schema version, treat the related examples, references, and publication pages as one release family. That keeps the public surface easy to navigate and the implementation easier to validate.