OpenAPI as the source of truth

API Craft treats the OpenAPI spec as the single source of truth for what an API is. But specs change, and you'll want to add things the upstream spec doesn't have. Better descriptions, extra parameters, notes. The trick is doing that without forking the spec into something that drifts.

Two inputs, one effective spec

There are only two things on disk:

  • spec.imported.json: the spec exactly as imported, converted to JSON. From your point of view it's immutable: it only changes when you import again or promote operations into it. You never edit it by hand.
  • Your overrides: the edits you make, stored in the business model: API-level overrides in api.json, resource- and operation-level overrides in _resource.json.

The effective spec is what you actually work against. It's computed in memory by projecting your overrides onto the imported spec. It is never written to disk; it's derived on demand and cached.

spec.imported.json  +  your overrides  ──►  effective spec (in memory)
   (immutable)          (api.json,
                         _resource.json)

Why this matters

  • No duplication. Operation details (parameters, schemas, responses) live only in the spec. Your overrides store just the difference, keyed by identity. A description you change is one field, not a copy of the whole operation.
  • No drift. Because the imported spec stays pristine, re-importing a new version is a clean three-way operation: old spec, new spec, your overrides.

You edit your resources and operations; the spec manager projects those edits into the effective spec. You never edit the spec directly.

Reading the effective spec

craftr spec read -a petstore-api            # the effective spec (overrides projected)
craftr spec read -a petstore-api --imported # the raw imported spec

Operations the spec doesn't have

Not every API starts from a spec. You can define operations yourself, or get them from a Postman or HAR import. A defined operation lives in your project files, contract included, and shows up in the effective spec like any other. When it's right, promote it: it moves into spec.imported.json, and the API then owns its spec ("specSource": { "type": "self" }). See Defining & promoting operations.

Re-importing

When the upstream spec changes, import again. API Craft diffs the new spec against the current one and reports the impact (added, removed, and modified operations, plus how each change interacts with your overrides and mapping rules) before applying anything. See Importing a spec for the full diff/merge workflow.