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.

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)

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)

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)

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

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

• Response schema
• Versioning and deprecation
• Errors