Materialize

Registered specs can be pulled into any repository with grapity materialize. This is useful for:

• Producers generating server stubs, types, or tests from their own spec.
• Consumers fetching a version-pinned contract to generate clients and types.

How it works

grapity materialize resolves the spec through the CLI auth, writes the pinned version to grapity.yaml, and records resolved/latest metadata in grapity-lock.json. It warns when the pinned version is no longer the latest registry version, so repos can detect drift in CI.

Configuration file

grapity.yaml declares which specs the repository consumes. It is created automatically on first materialize and can be edited by hand.

version: "1"

specs:
  - name: payments-api
    semver: "1.2.0"
    output: ./grapity/specs/payments-api.yaml
    format: yaml

  - name: users-api
    # omit semver to track latest; the CLI writes the resolved version back

Lockfile

grapity-lock.json records the resolved state at materialize time:

{
  "version": "1",
  "specs": {
    "payments-api": {
      "requested": "1.2.0",
      "resolved": "1.2.0",
      "latest": "1.3.0",
      "stale": true,
      "fetchedAt": "2026-06-20T12:00:00Z"
    }
  }
}

See also

• CLI Reference: grapity materialize — Full command usage and examples
• Registry Overview — How specs are stored and validated