Versioning and breaking changes
How Urd Atlas separates compatible additions, methodology changes and breaking API/schema changes.
Artifact identity
Published artifacts carry a layer schema_version. Meta rows additionally carry methodology_version and named regime rows carry regime.determinism_hash. Dataset manifests expose the active published schema families and publication revision.
Breaking changes
- Removing or renaming an existing response field or endpoint path.
- Changing a field type, unit, null meaning, required/optional status, or array/object shape incompatibly.
- Changing the semantic meaning of a regime label, score, date, evidence component or published artifact in a way existing consumers could misinterpret.
- Changing authentication requirements or entitlement scope for an existing documented subscriber path incompatibly.
- Changing a closed enum in a way an existing compliant parser is not expected to accept.
Non-breaking changes
- Adding an optional field whose absence remains valid for older clients.
- Adding a new endpoint without changing an existing one.
- Documentation corrections that do not change the data contract.
- Operational fixes that preserve documented field semantics and compatibility.
Notice policy
Urd Atlas targets at least 30 calendar days' public notice before a planned breaking API or schema change takes effect. Notice should identify the affected paths/fields, migration action, effective date and whether historical artifacts are republished.
Critical security, legal, corruption-repair or data-integrity fixes may require a shorter notice period. Those exceptions must be documented in the public changelog as soon as safely practical and must not be described as ordinary planned compatibility changes.
Methodology changes
A methodology-breaking analytical change is version-distinct even if the JSON shape itself remains parse-compatible. Customers comparing historical outputs should use methodology_version, schema version and provenance fields together. See the Methodology Changelog.