Envelope Schema Versioning Policy

The Envelope schema (.envelope.json) is an open standard. This document defines how the schema evolves, what counts as a breaking change, how versions are identified, and what obligations Envelope has to the ecosystem once the schema is public.

Core principle

The schema follows additive-only evolution within a major version. Once a major version is published, it cannot be broken — only extended. Breaking changes require a new major version, and old major versions are supported in perpetuity for existing definitions.

This is the same model as OpenAPI, JSON Schema, and npm. The builders who publish team definitions against v1 must be able to trust that their definitions keep validating forever.

Version identification

Versions are identified by a URI embedded in the $schema field of every team definition:

{
  "$schema": "https://schema.openenvelope.org/team/v1.json"
}

The version number (v1, v2, etc.) appears in the path. This is the contract reference — it tells every validator, adapter, and platform runtime exactly which version of the spec to apply.

Before launch

Until the first external builder publishes a team definition in production, the schema can be changed freely — including breaking changes — without a version bump. There are no external contracts to honour.

After the first external team is published: the policy below is binding.

Non-breaking changes (additive — ship freely)

These can be made to the current major version at any time without a version bump:

• Adding a new optional field anywhere in the schema
• Adding a new allowed value to an enum (e.g. a new adapter type, a new gate type, a new clearCondition)
• Loosening a validation constraint (widening a maxLength, making a minItems smaller)
• Adding new documentation, descriptions, or examples
• Deprecating a field in documentation without removing it (mark it deprecated: true in the spec, keep supporting it)
• Clarifying ambiguous wording in the spec without changing valid/invalid determinations

Process: update the schema file, update the docs, add a changelog entry. No ceremony required.

Breaking changes (require a major version bump)

These cannot be made to a published major version under any circumstances:

• Removing a field that existing definitions may use
• Renaming a field (this is a removal + addition)
• Making an optional field required
• Tightening a validation constraint (narrowing maxLength, making an enum more restrictive)
• Changing a field's type
• Changing the semantics of a field in a way that alters how valid definitions behave at runtime

Process: create v2 of the schema alongside v1. Both are served. Existing v1 definitions keep working. New definitions can target either version. Publish a migration guide.

Version lifecycle

What maintenance actually involves: an old schema version is a static JSON file served from a permanent URL. It does not rot, require dependency updates, or have security surface area. The only ongoing work is a single conditional branch in the Envelope runtime validator (if $schema == v1 → validate against v1, else v2) written once when v2 launches. Keeping v1 "maintained" is close to zero overhead.

Migration between major versions

When v2 is introduced:

1. Publish a migration guide (/docs/schema/migration-v1-v2) that lists every change and provides before/after examples for each one.
2. Provide a validator tool that accepts a v1 definition and reports which fields need changing to be v2-compatible.
3. Run both validators in parallel — accept both v1.json and v2.json in the $schema field.
4. Set a no-earlier-than date for v1 maintenance mode (minimum 12 months post-v2 launch).

Builders are never forced to migrate. Their v1 definitions continue to work. Migration is opt-in and they keep full control of when to do it.

Platform implementor obligations

Any platform implementing the Envelope schema (a conforming runtime) agrees to:

• Validate team definitions against the schema version declared in $schema
• Support every major version that is not yet Retired
• Not introduce extensions that conflict with reserved field names
• Report the schema versions they support via their adapter metadata

Platform-specific extensions are permitted only in a dedicated x-{platform} namespace (e.g. x-paperclip). Fields in that namespace are ignored by other platforms and never included in the core schema.

Deprecation process

Fields are deprecated before they are removed. The deprecation lifecycle:

1. Mark the field deprecated: true in the schema and add a note explaining the replacement.
2. Platform runtimes may warn (but must not error) when a deprecated field is present.
3. The field remains functional for the full maintenance window of that major version.
4. It may only be removed in a subsequent major version.

Version change notifications

Schema consumers who reference the schema URI directly (platform implementors, validator builders, adapter authors) are notified of version changes via the schema GitHub repository:

• Each new major version gets a tagged release (e.g. schema-v2.0.0) with release notes describing what changed and linking to the migration guide.
• Deprecations within a major version are noted in patch releases (e.g. schema-v1.1.0).
• Consumers who watch or star the repository receive GitHub notifications automatically.

Builders who use the Envelope web app are also notified via the in-app changelog (banner and blocking modal for breaking changes). The GitHub repository is the dedicated channel for schema-only consumers who do not use the app.

Reporting schema errors

If a builder or platform implementor finds a genuine error in a published schema version (a field incorrectly marked required, a regex that rejects valid values, a type mismatch), they open an issue in the Envelope schema GitHub repository. No special process, no email alias needed — GitHub Issues is the standard mechanism for every major open schema (JSON Schema, OpenAPI, AsyncAPI).

What counts as an error: the spec says one thing and the schema file enforces something different. A valid definition fails validation because of a bug in the schema itself.

What counts as a feature request: the spec is correct, but the builder wants it to work differently. Feature requests are discussed in issues and considered for the next additive update or next major version.

Turnaround: schema bugs that cause valid definitions to be rejected are treated as high priority. Schema bugs that are purely cosmetic (wrong description text, example typo) are batched with the next routine update.

Communication back to the reporter happens in the GitHub issue thread. No separate notification system is needed.

Who controls this

Envelope Ltd holds the canonical URI (schema.openenvelope.org) and is the steward of the specification. The schema is published under Apache 2.0 — anyone can fork it, implement it, or propose changes.

Material changes (anything that would require a version bump) are announced publicly with a minimum 60-day comment period before the new version is finalised. Minor additive changes can ship without a comment period.

Practical checklist before making any schema change

1. Is this change additive? (New optional field, new enum value, looser constraint)

   • Yes → ship freely. Update spec, update docs, add changelog entry.
   • No → see below.

2. Is this a breaking change?

   • Yes → is v1 still pre-launch? If so, make the change. If not, start the v2 process.

3. Am I removing or renaming anything?

   • Always breaking. Never do this in the current major version post-launch.

4. Am I making something required that was optional?

   • Always breaking. Never do this in the current major version post-launch.

5. Does my change affect how existing valid definitions behave at runtime?

   • If yes, it's breaking even if it looks structural. Get a second opinion.