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. 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 |