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 so on), 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, and so on) 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.

Next

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