# Blue Jetty contract versions

Use **configuration 0.5** for new app maps, including maps that use only fixed URLs. It describes publisher representation through `representation.summary`, optional `recommendationEligibility` and scoped `preferences`. Optional link recipes do not add an onboarding requirement.

Packet v2 uses wire version 0.2 at the same URLs. Public packets omit optional unpublished values and empty optional discovery collections. The filtered discovery object is not a complete submission. See [packet field semantics](/developers/packet-fields.md) for legacy header selection and [protocol semantics](/for-ai). Submission clear/reset semantics are unchanged.

| Contract | Current version | Purpose |
| --- | --- | --- |
| Managed app configuration | 0.5 | Publisher representation, capabilities, intents, destinations, MMP preferences, offers and optional link recipes |
| Entity/manifest/delivery profile | 0.1 | App identity, selected records, feeds and snapshot submission |
| HTTP API namespace | `/v1` | HTTP routes; independent of payload versions |
| Packet publication | 0.2 | Structured publisher preferences, handoff semantics and scoped evidence; source configuration version is independent |
| Publisher authorization proof | 0.1 | Exact server-issued proof; publish it unchanged |
| Publisher discovery descriptor | 1.0 | Stable pointers to both packet formats and selected delivery mode at `/.well-known/bluejetty.json` |
| Publisher-site check policy | 3 | Server-observed required/recommended discovery checks; independent of publisher payload versions |

## New publisher workflow

Create the app with the [publisher onboarding instructions](/developers/coding-agent-onboarding.md), then preview, stage and activate a configuration using the [0.5 guide](/developers/managed-configuration.md). Use the [0.5 schema](/schemas/v0.5/configuration.schema.json) for both fixed-link and recipe-enabled maps. Keep `specVersion: "0.1"` in entity submissions; configuration versions are not entity versions.

Publisher credentials manage app content. Agency credentials manage delegated relationships, analytics and authorized license operations; they cannot submit or activate a client's configuration. The invited publisher or their authorized coding agent performs those steps. See [agency instructions](/developers/agencies.md).

Use the [publisher-site instructions](/developers/publisher-discovery.md) to generate the discovery descriptor; do not substitute a configuration or ownership-proof document. The current `.well-known/bluejetty.json` path is Blue Jetty's discovery convention, not a claim of completed IANA registration. The canonical service origin is `https://bluejetty.ai`; legacy schema identifiers and existing proof bindings intentionally retain their original `bluejettyai.com` URLs and remain supported.

## Existing configurations and history

Configuration 0.2, 0.3 and 0.4 remain accepted under their released schemas. Stored revisions keep their original version. Their publisher text appears as attributed statements in packet v2 without requiring a publisher resubmission. The [0.2 schema](/schemas/v0.2/configuration.schema.json), [0.3 schema](/schemas/v0.3/configuration.schema.json) and [0.4 schema](/schemas/v0.4/configuration.schema.json) remain available for compatibility. Existing Swell Atlas and recipe fixtures retain their released input version.

For an approved 0.5 migration, move the app explanation to `representation.summary` and scoped source notes to `representation.preferences` using `statement` instead of `instruction`; preserve each ID and scope. Approve any substantive rewrite with the publisher. Recommendation eligibility is optional and is not inferred from prior defaults. The new schema rejects old instruction-field aliases so conflicting versions cannot coexist. Historical revisions are never rewritten.

For a compatibility-only 0.3-to-0.4 migration, keep its existing fields to retain fixed-link behavior. For a new map or migration to structured representation, use 0.5 as described above. Recipes are optional. For 0.2, also review attribution decoration: newer configurations preserve URLs by default. Explicitly approve any supported `append_missing` policy after reviewing your provider's settings. Do not infer tracking changes from a version bump.

Read the active configuration, preserve stable IDs, preview the complete replacement, stage it against the current `activeRevisionId`, inspect its diff, then explicitly activate. Arrays replace their previous values. Version changes do not confer publisher authority or change access permissions. Never rewrite historical revisions to make them appear to have used a newer contract.