Learn

Version Mismatch

How to resolve problems caused by mixing the wrong schema, page, or artifact version.

Troubleshooting map

The four version surfaces that must agree

Version mismatch usually appears because one of these public or working surfaces drifted away from the others.

File identityVersioned file path

The file name and folder should match the release family you think you are using.

Schema identity`$schema` and `$id`

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

Published routePage URL and visible copy

The public page should point at and describe the same version.

Support surfaceExamples, fixtures, and bundles

The surrounding artifacts should not silently point at a different release.

When one surface is wrong, realign it. Do not normalize the mismatch.

Version mismatch problems show up when the document and the schema are not talking about the same release family.

In Cuddler, version alignment is not optional. The instance "$schema" should match the canonical schema "$id", and the public page or artifact route should point at the correct versioned surface. If those drift apart, the right fix is to realign the version sources rather than paper over the mismatch.

Typical Signs

  • A page links to one version but the JSON points at another.
  • A schema update landed, but an example file still points to the older identity.
  • A convenience route is being treated like a canonical route.
  • A parent section describes one release while the child artifact bundle uses another.

What To Verify

  • The version number in the file path
  • The version number in the human-visible page title
  • The version number in the schema "$id"
  • The version number in the data or template "$schema"

Fix Order

  1. Identify the canonical version you want to keep.
  2. Update the data and template files to match that version.
  3. Update the page copy so the visible labels match the canonical version.
  4. Re-check the route and redirect behavior if the page is published publicly.