| title | Backward compatibility policy for the spec |
|---|---|
| navTitle | Backward Compatibility Policy |
| description | Versioning strategy, deprecation timelines, breaking change policy, and migration support for ObjectStack |
ObjectStack follows strict backward compatibility guarantees to ensure predictable upgrades and long-term stability for production deployments.
**Applies to:** `@objectstack/spec` and all packages in the ObjectStack ecosystem.**The 17.x minors ran under a launch-window override: a breaking change shipped as a MINOR release, not a MAJOR one.** Every published `@objectstack/*` package versions in lockstep, so the version number alone is not an upgrade-safety signal; read [Launch Window](#launch-window-minor-releases-can-contain-breaking-changes) at the end of this page before you upgrade across 17.x.
The v18 line has exited prerelease mode. While Changesets was in pre mode with the tag next, every release cut from main was the next 18.0.0-next.N on npm's next tag, and scripts/check-changeset-no-major.mjs stood aside in pre mode, so a pull request could declare a major bump. Changesets has exited pre mode, so the line's GA version is 18.0.0, which publishes to npm's latest tag, and the guard again fails a pull request that declares a major bump. See how a breaking stage lands on the v18 line.
After 18.0.0, a breaking change ships in a MINOR or a PATCH release. The maintainer's 2026-10-21 ruling (#25105) keeps the no-major guard and grades each change by the metadata protocol: a key, value or metadata type added, narrowed or given a new meaning takes MINOR, and every other change takes PATCH, breaking or not. A non-protocol breaking change (a REST response, a boot refusal, a CLI exit status, a removed runtime export) keeps its **BREAKING** banner and ships as a PATCH. 18.1.0, the first release under the rule, is a MINOR that carries 91 changesets declared breaking.
ObjectStack follows Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). The table below describes what each component means; which version a breaking change ships in depends on the line, as the callout above says.
| Version Component | When Incremented | Guarantee |
|---|---|---|
| MAJOR (X.0.0) | Incompatible API changes | May contain breaking changes |
| MINOR (0.X.0) | New features — and, in the 17.x minors, breaking changes; after 18.0.0, any change to the metadata protocol (added, narrowed or semantic) | Existing code may require migration; the release notes lead with what broke |
| PATCH (0.0.X) | Bug fixes — and, after 18.0.0, every change that is not to the metadata protocol, breaking ones included | Before 18.0.0, no behavior changes. After it, a PATCH can break a REST client, a boot or a script: read its release notes |
- Zod schemas are part of the public API surface. Adding optional properties is a MINOR change; removing or renaming properties is a breaking change, which the 17.x minors also shipped in a MINOR release.
- TypeScript types inferred from Zod (
z.infer<typeof Schema>) follow the same guarantees as their source schemas. - Helper functions (e.g.,
defineStack,defineStudioPlugin) maintain their call signatures within a MAJOR version. - Input formats —
defineStack()accepts both array and map (Record) format for all named metadata collections. Both formats are guaranteed stable within a MAJOR version. - Enum values are append-only within a MAJOR version. Existing values are never removed or renamed in MINOR/PATCH releases.
- Default values in schemas are not changed in MINOR/PATCH releases unless fixing a documented bug.
{/* os:check */}
// These imports are guaranteed stable within a MAJOR version
import { FieldSchema, ObjectSchema } from '@objectstack/spec/data';
import { defineStack } from '@objectstack/spec';
import { defineStudioPlugin } from '@objectstack/spec/studio';When a feature, schema property, or API is deprecated, ObjectStack follows a structured wind-down process:
- Feature is marked
@deprecatedin JSDoc comments - Zod schema property gets a
.describe('DEPRECATED: ...')annotation - Runtime warning is emitted on first use (once per session)
- Migration path is documented in the CHANGELOG
- Deprecated feature continues to function without behavior changes
- Documentation is updated with migration guides
- Code examples are updated to use the replacement
- CLI tooling may provide automated migration commands
- Deprecated feature is removed from the schema
- TypeScript types no longer include the property
- Runtime code no longer supports the feature
- The removal is called out in the release notes and marked
**BREAKING**in the changeset
Shipped examples: 17.2.0 retired http_request_errors_total and sys_position.permissions under ADR-0049 enforce-or-remove, and 15.1.0 removed tenancy.strategy and tenancy.crossTenantAccess — all three in Minor Changes sections.
flowchart TD
A["Deprecation notice — feature marked deprecated (warning emitted)"] --> B["Migration period — deprecated feature keeps working, no behavior change"]
B --> C["Removal — retired at the boundary the ADR-0087 registry records (MINOR release in 17.x, the next 18.0.0-next.N during the v18 prerelease)"]
Read the Breaking? column, not the version number: in the 17.x minors every row below — breaking or not — shipped in a MINOR or PATCH release, and during the v18 prerelease every row shipped in the next 18.0.0-next.N, so in neither case does the bump size tell you whether you have work to do.
| Change Type | Breaking? | Version Impact (17.x minors) |
|---|---|---|
| Removing a schema property | Yes | MINOR |
| Renaming a schema property | Yes | MINOR |
| Changing a property from optional to required | Yes | MINOR |
Narrowing a type (e.g., string → enum) |
Yes | MINOR |
| Removing an enum value | Yes | MINOR |
| Changing default values | Yes | MINOR |
| Adding a new optional property | No | MINOR |
| Adding a new enum value | No | MINOR |
Widening a type (e.g., enum → string) |
No | MINOR |
| Adding a new schema/export | No | MINOR |
| Fixing validation to match documented behavior | No | PATCH |
| Fixing typos in descriptions | No | PATCH |
- RFC (Request for Comments) — Breaking changes are proposed as GitHub issues with the
protocol:breakinglabel. - Deprecation — The old behavior is deprecated in a MINOR release (see timeline above).
- Migration Guide — A detailed migration guide is published before the removal lands, in the release notes for the version that carries it.
- Release — In the 17.x minors the breaking change shipped in the next MINOR version, carrying a changeset entry marked
**BREAKING**, andscripts/check-changeset-no-major.mjsfailed a pull request that declared amajorbump, because under lockstep onemajorwould promote all 111 published packages. During the v18 prerelease it shipped in the next18.0.0-next.N, because the guard stood aside in pre mode and a pull request could declare a major bump. Changesets has exited pre mode, so the guard fails amajorbump again. See how a breaking stage lands on the v18 line.
The CLI's lint command checks your metadata for style and convention issues and surfaces them. Adding --fix prints the suggested fix for each issue (dry-run; it does not modify files):
# Check metadata for style and convention issues
os lint
# Show what could be auto-fixed (dry-run)
os lint --fix
# Scan your source for deprecated ObjectStack patterns
os doctor --scan-deprecations
# Compare two configs and detect breaking changes between versions
os diff <before> <after> --breaking-onlyEach MAJOR release includes:
- CHANGELOG.md — Complete list of changes with migration notes
- RELEASE_NOTES.md — High-level summary and upgrade instructions
- Schema Diff — Use
os diff <before> <after>to produce a machine-readable (--json) diff of breaking changes between two configs
Only the current MAJOR receives fixes. There is no maintenance line for an older MAJOR: compatibility across majors is carried by the protocol's conversion layer and migration chain (ADR-0087), not by patching old releases.
- The current MAJOR — bug fixes and security patches ship in the next release cut from
main. While the next MAJOR is in prerelease, every release cut frommainis one of its prereleases on the pre-mode dist-tag (nexton the v18 line), so a fix reacheslatestonly when that MAJOR goes GA. - The previous MAJOR, and every older one — receives no fixes, and no backport or maintenance release is promised. To take a fix, upgrade to the current MAJOR.
- The conversion layer (ADR-0087 D2) — as the runtime loads your metadata, it converts the previous MAJOR's lossless changes (renames, alias removals, field moves) to the current shape and emits a deprecation notice per conversion, so those shapes keep loading after you move the runtime forward. It covers only the previous MAJOR and only lossless changes;
os migrate metacarries everything else. os migrate meta(ADR-0087 D3) —os migrate meta --from Nreplays the migration chain from the major your metadata was authored against (protocol 16 or later, the chain's floor) to the current one in a single pass, and lists the edits your source needs; with--writeit writes the mechanical ones it can trace to one literal into your source files. It reads no database.os migrate meta --storedreplays the same chain over one deployment's storedsys_metadatarows and, with--apply, rewrites the ones still carrying an older shape. See the CLI reference and Upgrading → The metadata app.- Testing a MAJOR before it reaches
latest—scripts/check-changeset-no-major.mjsfails a pull request that declares amajorbump outside Changesets pre mode and stands aside inside it, and a MAJOR declared in pre mode publishes only prereleases, on the pre-mode dist-tag, until pre mode exits; the v18 line usednext(18.0.0-next.0…18.0.0-next.5) before 18.0.0. Install from that tag to run your app against a MAJOR before it becomeslatest.
The @objectstack/spec package provides additional stability guarantees:
- All Zod schemas are validated by comprehensive test suites
- Schema changes require both Zod and JSON Schema output validation
- Property additions must include
.describe()annotations and.optional()or.default()markers
- All public exports are listed in the package's
index.tsbarrel files - Removing an export is always a breaking change; the 17.x minors shipped it in a MINOR release, and during the v18 prerelease it shipped in the next
18.0.0-next.N - Internal modules (prefixed with
_or ininternal/directories) are not covered by SemVer guarantees
Schema.parse()results are guaranteed consistent within a MAJOR version- Default values applied by
.default()are stable within a MAJOR version - Validation error messages may change in MINOR/PATCH releases (do not rely on exact error text)
**The 17.x minors ran under this exception — read it before you upgrade across them.** Every published `@objectstack/*` package versions in **lockstep**, and in the 17.x minors a breaking change shipped as a **MINOR** release rather than burning a MAJOR, so those minors contain documented breaking changes. During the v18 prerelease every release cut from `main` was the next `18.0.0-next.N` on npm's `next` tag; Changesets has exited pre mode, so the line's GA version is `18.0.0`, which publishes to npm's `latest` tag. See [how a breaking stage lands on the v18 line](/docs/releases/v18#how-a-breaking-stage-lands-on-this-line).
All of them. It was not scoped to an experimental corner or a pre-release channel: all 111 packages published from this repository belong to a single Changesets fixed group, so they share one version number and one policy. No published surface was exempt.
The convention was enforced rather than informal — scripts/check-changeset-no-major.mjs failed a pull request that introduced a major bump, because under lockstep a single major on one package would promote the entire stack. During the v18 prerelease Changesets was in pre mode with the tag next and the guard stood aside, so a pull request on the v18 line could declare a major bump. Changesets has exited pre mode, and the guard fails a major bump again.
- Do not read a MINOR bump as safe to take unattended. Read the release notes for the version you are moving to: they lead with breaking changes and carry the migration steps.
- Pin exact versions instead of caret ranges if you cannot review each MINOR before it lands, and after 18.0.0 each PATCH as well.
- Diff your own metadata across the upgrade with
os diff <before> <after> --breaking-only.
MAJOR releases do still happen — 17.0.0 was cut precisely because its breaking density was too high to carry ^16.x consumers across on a caret range, and the v18 line is the next one — but in the 17.x minors an individual breaking change did not, on its own, force one.
The tables and deprecation timeline above state this rule for the 17.x minors directly, beside what the v18 prerelease did. Classic SemVer — where a breaking change once again requires a MAJOR — is the settled form the project returns to once the launch window closes. It did not close at the 18.0.0 GA. The 2026-10-21 ruling (#25105) keeps the no-major guard on the v18 line and grades each change by the metadata protocol instead, so after 18.0.0 a breaking change ships in a MINOR when it narrows the metadata protocol and in a PATCH when it does not. For the 17.x minors, this section was the operative rule wherever any part of this page disagreed. For the 18.0.0-next.N prereleases, the operative rule is how a breaking stage lands on the v18 line. For the releases after 18.0.0, it is that ruling: read every release's notes, PATCH releases included, and pin exact versions.
If you encounter an unintended breaking change:
- Check the CHANGELOG — Verify the change was not documented as intentional.
- Open an issue — File a GitHub issue describing the unintended change.
- Include a reproduction — Provide a minimal code sample showing the breakage.
- Reference the version — Specify the exact versions where behavior changed.