XcodeBuildMCPdocs
⌘ K
Install
Docs/Contributing/Schema Versioning

Schema Versioning

How XcodeBuildMCP versions, publishes, and maintains structured output JSON Schemas served from xcodebuildmcp.com.

XcodeBuildMCP publishes structured output schemas at stable website URLs. External consumers can validate CLI JSON output and MCP structuredContent against those schemas, so schema changes need the same care as any public contract.

Goals#

  • Keep schema contracts stable and predictable for external consumers.
  • Make published schema URLs real, durable, and safe to reference.
  • Serve schemas directly from https://xcodebuildmcp.com/schemas/....
  • Avoid ambiguous compatibility rules.

Canonical schema identity#

Each structured payload has two stable identifiers:

json
{
  "schema": "xcodebuildmcp.output.build-result",
  "schemaVersion": "1"
}

The matching published schema URL is:

text
https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.build-result/1.schema.json

The in-payload schema and schemaVersion values must always match the published schema document that validates that payload.

Version format#

schemaVersion uses integer strings only:

  • "1"
  • "2"
  • "3"

Do not use semver-style schema versions such as "1.1" or "2.0". The version number is a contract version, not a release number.

Versioning rules#

Published versions are immutable#

Once a schema version is published, do not make breaking changes to that file.

Breaking changes include:

  • Removing a property.
  • Making an optional property required.
  • Narrowing allowed values or enums.
  • Changing object shape incompatibly.
  • Changing field meaning in a way that could break clients.

If any of those changes are needed, publish a new version instead:

text
schemas/structured-output/xcodebuildmcp.output.build-result/2.schema.json

Then emit:

json
"schemaVersion": "2"

Old versions remain available#

Previously published schema files must continue to be hosted. Do not remove old schema versions from the website once consumers may rely on them.

Additive changes#

Additive optional fields can be compatible, but use caution. If a new field is truly optional and old clients can safely ignore it, it may remain within the same schema version. If there is any doubt about compatibility or meaning, bump the schema version.

Bias toward a new version when the contract meaning changes.

Directory layout#

Source schemas in the main repository live under:

text
schemas/structured-output/

Published schemas on the website live under:

text
public/schemas/structured-output/

A source file such as:

text
schemas/structured-output/xcodebuildmcp.output.build-result/1.schema.json

is published to:

text
public/schemas/structured-output/xcodebuildmcp.output.build-result/1.schema.json

The website then serves it at:

text
https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.build-result/1.schema.json

Publishing workflow#

Schema publishing is handled from the main repository by a GitHub Actions workflow.

Trigger conditions:

  • Push to main when files under schemas/** change.
  • Manual workflow_dispatch.

Publishing steps:

  1. Check out getsentry/XcodeBuildMCP.
  2. Clone getsentry/xcodebuildmcp.com over SSH.
  3. Sync schemas/structured-output/ into public/schemas/structured-output/ in the website repository.
  4. Commit the website change if the published files changed.
  5. Push to the website repository main branch.
  6. Let Vercel deploy the website normally.

This keeps schema authoring in the main project repository while using the website repository as the deployment surface.

Required secret#

The publishing workflow requires this repository secret:

text
XCODEBUILDMCP_WEBSITE_DEPLOY_KEY

This secret must contain an SSH private key with write access to:

text
git@github.com:getsentry/xcodebuildmcp.com.git

The corresponding public key should be installed as a deploy key on the website repository with write access.

Deploy key setup#

  1. Generate a dedicated SSH key pair for schema publishing.

    shell
    ssh-keygen -t ed25519 -C "schema-publisher" -f ./xcodebuildmcp-website-deploy-key

  2. In getsentry/xcodebuildmcp.com, add the public key as a deploy key with write access.

  3. In getsentry/XcodeBuildMCP, add the private key as an actions secret named XCODEBUILDMCP_WEBSITE_DEPLOY_KEY.

  4. Trigger the Publish Schemas workflow manually once to verify SSH access and sync.

  5. Confirm that the website repository receives the commit and Vercel deploys it.

  6. Confirm a final URL resolves, for example:

    text
    https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.build-result/1.schema.json

Use a dedicated deploy key for this workflow only. Do not reuse a personal SSH key.

Consumer guidance#

Consumers should branch on both schema and schemaVersion:

ts
switch (`${payload.schema}@${payload.schemaVersion}`) {
  case "xcodebuildmcp.output.build-result@1":
    // validate using v1 schema
    break
  case "xcodebuildmcp.output.build-result@2":
    // validate using v2 schema
    break
  default:
    throw new Error("Unsupported schema version")
}

These JSON Schemas describe payload shapes. They are not an OpenAPI description by themselves. If an HTTP API is introduced later, OpenAPI should reference the schema files as component schemas instead of trying to infer endpoints from them.

Maintenance checklist#

When updating schemas:

  1. Decide whether the change is compatible or breaking.
  2. If breaking, add a new versioned schema file instead of changing the old one.
  3. Update fixture payloads to emit the correct schemaVersion.
  4. Run npm run test:schema-fixtures.
  5. Merge to main.
  6. Confirm the publish workflow updated the website repo.
  7. Confirm the final schema URL resolves on the website.
← Previous
Tool Authoring