# Schema compatibility (/docs/schema-compatibility)

How SocialCrawl classifies additive changes, value corrections, format corrections, and breaking changes to a versioned unified response object

Every canonical object is a versioned contract. `dev.socialcrawl.post.v1`, `dev.socialcrawl.author.v1`, and the other unified response schemas change in exactly three ways. A fourth kind of change is never applied to a published version.

| Class             | What changes                                                      | How you hear about it        |
| ----------------- | ----------------------------------------------------------------- | ---------------------------- |
| Additive          | A new optional field appears                                      | Changelog entry              |
| Value correction  | An existing field carries a corrected value, same name, same type | Changelog entry              |
| Format correction | An existing field's format or type changes                        | Email, at least 7 days ahead |
| Breaking          | Never applied to a published version, it ships as a new schema id | New schema id                |

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 classes below turn on.

## Additive changes

A new field is always optional: either nullable and optional, or namespaced under `ext.*`. Old clients are unaffected because the field may be absent. This is the default, and it covers all enrichment.

## Value corrections

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 and 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 and type corrections

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. Affected
  customers get an email notice at least 7 days before it ships, showing both
  the old format and the new one.

## What is never done to a published version

Removing a field, renaming a field, changing a field's type, and making an optional field required are never done to a published `.vN`. The replacement path is always the same:

- Keep the old field, marked deprecated.
- Add the new field alongside it.
- Mint a new schema id such as `dev.socialcrawl.post.v2`.

An automated compatibility check blocks any release that removes, retypes, or newly requires a published field.

## Which changes count as breaking

| Breaking                                              | Not breaking                   |
| ----------------------------------------------------- | ------------------------------ |
| Removing a field                                      | Adding an optional field       |
| Renaming a field                                      | Adding a value to an open enum |
| Changing a field's type                               | Loosening a constraint         |
| Tightening a constraint, such as optional to required | Adding a new object            |
| Narrowing an enum                                     |                                |

## Next steps

- [Unified schema](/docs/schema.md): Every field on every canonical object.
- [Response schema](/docs/response-schema.md): The envelope those objects arrive in.
- [Versioning](/docs/versioning.md): How versions are published and retired.
- [Errors](/docs/errors.md): Error codes, statuses, and refund rules.