# Schema Compatibility Promise (/docs/schema-compatibility) Schema Compatibility Promise [#schema-compatibility-promise] Every canonical object (`dev.socialcrawl.post.v1`, `dev.socialcrawl.author.v1`, and the other unified response schemas) is a versioned contract. Changes are classified into exactly three allowed classes and one forbidden class. The full field list for each object is browsable under [Unified schema](/docs/schema.md). Check there first when you need to know whether the field you depend on is a published `.v1` leaf or an `ext.*` addition — that distinction is what the four classes below turn on. Additive (safe, any time) [#additive-safe-any-time] A new field is always optional, either nullable and optional or under an `ext.*` namespace. Old clients are unaffected because the field may be absent. This is the default and covers all enrichment. Correction (allowed with a regression test and a changelog entry) [#correction-allowed-with-a-regression-test-and-a-changelog-entry] The value filling an existing field changes because it was wrong: a misplaced leaf, a wrong source path, or a stale mapping. The contract does not change: same field, same type. A value correction makes existing parsers work better with no code change, so it ships with a changelog entry and no direct notice. Format/type correction (allowed with a 7-day direct notice) [#formattype-correction-allowed-with-a-7-day-direct-notice] An existing field's format or type changes. The timestamp dialect migration is the one case in the current schema program. A format change can break a parser that assumed the old format, so affected customers get an email notice at least 7 days before ship, showing both the old and new format. Forbidden without a new schema id (breaking) [#forbidden-without-a-new-schema-id-breaking] Removing a field, renaming a field, changing a field's type, or making an optional field required are never done to a published `.vN`. Instead: * Keep the old field marked deprecated. * Add the new field alongside it. * Mint a new schema id such as `dev.socialcrawl.post.v2`. The CI compatibility gate fails any build that removes, retypes, or newly requires a published field. What Counts As Breaking [#what-counts-as-breaking] Breaking changes include removing a field, renaming a field, changing a type, or tightening a constraint such as optional to required or wide enum to narrow enum. Non-breaking changes include adding an optional field, adding a value to an open enum, loosening a constraint, or adding a new object. Related [#related] * [Unified schema reference](/docs/schema.md) * [Response schema](/docs/response-schema.md) * [Versioning and deprecation](/docs/versioning.md) * [Errors](/docs/errors.md)