This page as Markdown, byte for byte: /open-schema.md

The open schema#

The canonical risk object is Craton's core primitive, and its JSON Schema is open. You can fetch it, read it, validate against it and build on it with no Craton account — nothing to authenticate, nothing to install, nothing that expires. The engine is paid; the vocabulary is not.

This page shows the whole of that: resolve which file to use and which version this deployment emits, fetch it, and validate an object of your own against it in one run.

What you need#

• curl 7.76 or newer (this page uses --fail-with-body) and python3 3.8 or newer. Nothing else — the validator below is standard library only.
• CEDE_DOCS_URL — the base URL of a Craton documentation site. That is the only address on this page: the API is not involved, and no credential is sent anywhere.

export CEDE_DOCS_URL="https://docs.oncraton.com"   # no trailing slash

Craton is pre-release, and the site above is reachable to members of the operator's tailnet rather than to the open internet — a public address is waiting on a domain. Point CEDE_DOCS_URL at any Craton documentation site someone runs for you and nothing else on this page changes.

What is published#

$CEDE_DOCS_URL/schema lists every published file, with the version this deployment stamps on the documents it emits. The files are:

These are the same files Craton validates its own responses against — not a copy published for readers. A response that fails one of them is a product bug, and the gate that says so reads the file you just downloaded.

Versions, and what a version line means#

A file name carries the version line, not the version: risk-object.v0.schema.json accepts every 0.x.y document. That is deliberate — a minor version that adds optional members must never retroactively invalidate an object you already hold — and it leaves one question the files alone cannot answer: which version is this deployment emitting? That is what versions.emitted in the contract is for, and the block below resolves it rather than trusting a number typed on a page.

Breaking changes bump the major version and arrive as a new file (risk-object.v1.schema.json), never as an edit to this one. So a URL you link, cite or pin in your build is stable: the bytes behind $CEDE_DOCS_URL/schema/risk-object.v0.schema.json are only ever extended compatibly.

Fetch and validate, end to end#

Copy the block. It fetches the contract, resolves the file and the version, downloads the schema and the validator, validates an object it writes, and then proves the validator bites by feeding it a broken one.

set -euo pipefail

: "${CEDE_DOCS_URL:?export CEDE_DOCS_URL first — see 'What you need'}"

read_json() {
  python3 -c 'import json, sys
document = json.load(open(sys.argv[1]))
for step in sys.argv[2].split("."):
    document = document[step]
print(document)' "$1" "$2"
}

# 1 — The contract: which file governs the risk object, and which version of
#     it this deployment emits. No key is sent, and none is asked for.
curl -sS --fail-with-body "$CEDE_DOCS_URL/schema/api-contract.v0.json" \
  -o api-contract.v0.json

schema_file="$(read_json api-contract.v0.json schemas.risk-object)"
version="$(read_json api-contract.v0.json versions.emitted.risk-object)"
echo "risk object: $schema_file, emitted version $version"

# 2 — The schema itself, and the validator that ships beside it. Standard
#     library only: nothing to install, nothing to trust but python3.
curl -sS --fail-with-body "$CEDE_DOCS_URL/schema/$schema_file" -o "$schema_file"
curl -sS --fail-with-body "$CEDE_DOCS_URL/schema/validate.py" -o validate.py

# 3 — An object of your own, stamped with the version resolved above rather
#     than one copied off a page. A draft needs exposure and nothing else:
#     source_fidelity is mandatory and its three lists are mandatory empty,
#     so "nothing was guessed" has to be stated, never left to silence.
python3 - "$version" > my-object.json <<'PY'
import json, sys
print(json.dumps({
    "schema_version": sys.argv[1],
    "status": "draft",
    "exposure": {
        "kind": "location_schedule",
        "currency": "USD",
        "locations": [{
            "address_as_given": "1 Harbour Road, Miami FL",
            "geocode": {"resolution": "unknown"},
        }],
        "source_fidelity": {
            "unmapped_columns": [],
            "guessed_units": [],
            "ambiguous_rows": [],
        },
    },
}, indent=2))
PY

# 4 — Validate. Exit 0 means the object conforms to the published schema.
python3 validate.py --schema "$schema_file" my-object.json

# 5 — And prove the validator bites, because a validator that accepts
#     everything would have printed the same green line above. This object
#     names a peril outside the closed taxonomy.
python3 - "$version" > broken-object.json <<'PY'
import json, sys
print(json.dumps({
    "schema_version": sys.argv[1],
    "status": "analysed",
    "exposure": {
        "kind": "index",
        "source_fidelity": {
            "unmapped_columns": [],
            "guessed_units": [],
            "ambiguous_rows": [],
        },
    },
    "peril": {"code": "meteor_strike"},
}, indent=2))
PY

if python3 validate.py --schema "$schema_file" broken-object.json; then
  echo "the validator accepted an object it should have refused" >&2
  exit 1
fi
echo "refused, as it should be — the schema is doing work"

What you get from step 4 is a line naming the schema and the verdict, and an exit status you can put in your own build. Nothing on this page contacted the API, so nothing here depends on having an account, a key, or a plan.

What the validator adds#

Two rules the specification states and JSON Schema has no keyword for, applied by validate.py on top of the schema:

• S1 — period.expiry must be strictly after period.inception. No keyword compares two sibling values.
• S2 — period.timezone must name a real IANA zone, checked against your machine's tz database. Where there is no tz database, it says so out loud instead of passing over it.

It also refuses to load a schema containing a keyword it does not implement: a validator that ignores what it does not understand under-validates without telling you. If you would rather use your own implementation, the files are plain JSON Schema draft 2020-12 and every published draft 2020-12 validator reads them — validate.py is a convenience, not a dependency.

Validating what the API sends you#

Once you do hold a key, the same files validate every response. Read api-contract.v0.json as four rules:

• routes — for a 2xx, take answers[status] and validate the body against schemas[that id].
• errors — any status of 400 or above, from any route, validates against the error schema. One refusal shape for the whole surface.
• embedded — a published document carried inside another at a JSON pointer: a technical price travels inside the job that produced it, and a backtest and a model run do the same. Follow the pointer and validate it in full.
• versions.emitted — the version each of those documents is stamped with, which is the number step 1 above resolves.

The contract is generated from the server's own route registrations, and the contract oracle fails the build if the published map and the running surface disagree in either direction. A route the map does not document is a red gate, not an undocumented feature.

The quickstart takes it from there: signup, a key, an ingest call, and a first object of your own to run through the validator above.

What is open, and what is not#

The schema is open source. The engine behind the verbs — normalisation, hazard data, pricing, backtesting, the registry — is the paid product, billed by usage with a free sandbox tier. Building your own tooling against these files, publishing objects that conform to them, or writing your own validator needs nothing from Craton and asks nothing of you.

Craton outputs technical prices with their assumptions attached and draft terms. It holds no money and never touches paper; nothing produced by anything on this page is a transaction or a position anyone stands ready to take.