Output contracts & schemas

Everything that consumes Shipmoor — your CI scripts, the Agent Harness, the IDE extension, your own tooling — reads one of three stable, versioned JSON contracts. They’re designed to be scripted against: gate on schema_version, ignore unknown fields, and they won’t break under you.

The three contracts

shipmoor.scan.v1

The scan report. Key fields per finding: id (stable SHM-…), rule_id, severity, path, start_line, message, recommendation, evidence, subtype, change_status (introduced / modified / preexisting / unknown on diff/patch scans), and a stable fingerprint for deduplication. See Output formats & exit codes.

With an intent supplied, the claim check rides as an additive change_results[] array (absent entirely on a no-intent scan):

{
  "verdict": "major_gap",
  "maturity": "gap_disclosed",
  "coverage": 1.0,
  "gate_decision": "not_evaluated",
  "resolved_intent": { "goal_text": "…", "confidence": "medium" },
  "evidence": [ { "result": "unsatisfied", "basis": "deterministic" } ],
  "per_probe_summary": { "satisfied": 3, "unsatisfied": 0, "cannot_check": 0, "unmatched": 1 },
  "plan_drift_summary": { "has_drift": false, "classes": [] },
  "fingerprint": "sha256:…"
}

See Reading the verdict for the field semantics.

shipmoor.identity.v1 and shipmoor.capabilities.v1

Two documents, not one: capabilities is a superset of identity (same fields, plus the capabilities map). The shapes, the documented account states (active, trialing, in-grace, past-grace, …), and the stable reason codes are covered in Capabilities & entitlements and Sign in & licensing.

The contract rule that matters for consumers: gate features on capabilities.<name>.enabled — never on plan or tier, which are informational and open vocabularies.

One vocabulary, defined once

The entitlement names inside these payloads (intent_scan, agent_skills, agent_harness, ide_extension_pro, …) are defined in a single shared source inside the product — every surface imports the same definition, and CI checks enforce that the license issuer and the binary can’t drift apart. Practically: an entitlement string means the same thing in whoami, capabilities, the skills installer, and the harness, always.

Versioning and compatibility

The contracts are additive within v1:

• New optional fields, new entitlement strings, and new reason codes may appear without a version bump — consumers must tolerate them (degrading unknown paid things to “hidden”).
• Breaking changes (removing fields, changing semantics) require a .v2, with both versions emitted in parallel for a deprecation window.
• Always gate on schema_version before parsing version-specific fields.

Two privacy properties hold across all three: payloads never contain raw license tokens (the source field is a category — none/env/file — never a path), and never contain source code, diffs, or repo contents.

Related machine surfaces with their own schemas: SARIF 2.1.0 from scan --sarif, shipmoor.skills.install.v1 from skills install --json, and shipmoor.harness.status.v1 from shipmoor-harness status --json (preview).

Next

• Output formats & exit codes — scan.v1 in day-to-day use.
• Capabilities & entitlements — the entitlement contract in depth.
• Agent Harness overview (preview) — a real consumer of all three.