Schema · coordinator/step

Coordinator step definition, v0 (draft)

A step is a signed, content-addressed WebAssembly program the coordinator evaluates on facts it already holds. Draft design artifact for the RFC 'Distributed and Programmable Coordinator as a Service'; nothing evaluates it yet. Deny by default: a step names every capability it uses, and the list of nameable capabilities is closed.

The schemas and their descriptions are in English only.

01Versions

Each version is a file at its own address. The raw file is plain JSON, served without a sign-in.

v0draftMay still be corrected; kept for five minutes.schemas.inorbit.hr/coordinator/step/v0.json ↗

02Fields

Fields of v0, the newest version, by path. A name ending in [] is each item of a list. Every field not listed is refused.

Field	Type	Required	What it is	Rules
schema	const	yes		always "https://schemas.inorbit.hr/coordinator/step/v0.json"
id	string	yes	Stable name of the step inside its account.	pattern ^[a-z][a-z0-9-]{2,62}$
version	integer	yes	Immutable once validated; a change is a new version.	at least 1
title	string	no		at most 120 characters
kind	one of	yes	gate and check return a decision; score returns a number. All are pure: facts in, result out.	"gate", "check", "score"
program	object	yes
program.format	one of	yes	core-abi-1 is the module ABI of RFC 0135 slice 1a; component is a WebAssembly component (WIT world below).	"core-abi-1", "component"
program.world	string	yes		pattern ^iohr:coordinator/step@[0-9]+\.[0-9]+\.[0-9]+$
program.digest	string	yes	SHA-256 of the .wasm bytes. The id and version name exactly one binary.	pattern ^sha256:[0-9a-f]{64}$
program.size_bytes	integer	yes		1 to 4194304
program.source_language	string	no	Informational. The runtime never sees source.	pattern ^[a-z][a-z0-9+.-]{0,23}$
facts	list of string	no	The fact names the step reads. A fact outside this list is not handed to it, and a fact of a classified or local data class is never handed to any step.	at most 64 items; no repeats; each: pattern ^[a-z][a-z0-9_.]{0,63}$
capabilities	list of one of	yes	Closed list. No network, files, clock, randomness, environment or process access can be named, so none can be granted.	at most 3 items; no repeats; each: "facts.read", "decision.emit", "trace.event"
limits	object	yes	Ceilings the host enforces; the platform's own maxima apply on top.
limits.fuel	integer	yes		1 to 1000000000
limits.memory_bytes	integer	yes		65536 to 67108864
limits.wall_ms	integer	yes		1 to 1000
limits.output_bytes	integer	no		1 to 65536
limits.host_calls	integer	no		0 to 4096
metering	object	no	Which coordinator unit category an evaluation reports. Accounts' catalogue prices it; the step never does.
metering.unit	one of	yes		"step.eval", "step.fuel_mega"
authoring	object	yes
authoring.admin_only	const	yes		always true
authoring.author	string	yes	The verified subject Envoy forwarded, recorded by the service; a request cannot claim another.	at least 1 characters; at most 128 characters
signature	object	no	Over the canonical JSON of this document without this field. Absent means unsigned: validates, cannot run.
signature.alg	const	yes		always "ed25519"
signature.key_id	string	yes		at least 1 characters; at most 128 characters
signature.value	string	yes		pattern ^[A-Za-z0-9_-]{86}$

03Example

A valid document, with made-up values, as the repository's tests check it (gate-hold-migration-and-route.json).

{
  "schema": "https://schemas.inorbit.hr/coordinator/step/v0.json",
  "id": "hold-migration-and-route",
  "version": 1,
  "title": "Hold a job whose PR changes a migration and a route together",
  "kind": "gate",
  "program": {
    "format": "core-abi-1",
    "world": "iohr:coordinator/step@0.1.0",
    "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "size_bytes": 18432,
    "source_language": "rust"
  },
  "facts": ["pr.paths", "pr.labels"],
  "capabilities": ["facts.read", "decision.emit"],
  "limits": { "fuel": 5000000, "memory_bytes": 1048576, "wall_ms": 5, "output_bytes": 1024, "host_calls": 64 },
  "metering": { "unit": "step.eval" },
  "authoring": { "admin_only": true, "author": "example-admin-subject" }
}

The repository's tests also check 6 documents that this schema must refuse.

04Check a file against it

Replace the file name with yours.

VS Code, JetBrains: settings (JSON)

"json.schemas": [
  { "fileMatch": ["my-file.json"], "url": "https://schemas.inorbit.hr/coordinator/step/v0.json" }
]

check-jsonschema

check-jsonschema --schemafile https://schemas.inorbit.hr/coordinator/step/v0.json my-file.json

ajv-cli

ajv validate --spec=draft2020 -s <(curl -s https://schemas.inorbit.hr/coordinator/step/v0.json) -d my-file.json

curl

curl -s https://schemas.inorbit.hr/coordinator/step/v0.json

05The schema itself

Raw JSON ↗

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.inorbit.hr/coordinator/step/v0.json",
  "title": "Coordinator step definition, v0 (draft)",
  "description": "A step is a signed, content-addressed WebAssembly program the coordinator evaluates on facts it already holds. Draft design artifact for the RFC 'Distributed and Programmable Coordinator as a Service'; nothing evaluates it yet. Deny by default: a step names every capability it uses, and the list of nameable capabilities is closed.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema", "id", "version", "kind", "program", "capabilities", "limits", "authoring"],
  "properties": {
    "schema": {
      "const": "https://schemas.inorbit.hr/coordinator/step/v0.json"
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]{2,62}$",
      "description": "Stable name of the step inside its account."
    },
    "version": {
      "type": "integer",
      "minimum": 1,
      "description": "Immutable once validated; a change is a new version."
    },
    "title": { "type": "string", "maxLength": 120 },
    "kind": {
      "enum": ["gate", "check", "score"],
      "description": "gate and check return a decision; score returns a number. All are pure: facts in, result out."
    },
    "program": {
      "type": "object",
      "additionalProperties": false,
      "required": ["format", "world", "digest", "size_bytes"],
      "properties": {
        "format": {
          "enum": ["core-abi-1", "component"],
          "description": "core-abi-1 is the module ABI of RFC 0135 slice 1a; component is a WebAssembly component (WIT world below)."
        },
        "world": {
          "type": "string",
          "pattern": "^iohr:coordinator/step@[0-9]+\\.[0-9]+\\.[0-9]+$"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[0-9a-f]{64}$",
          "description": "SHA-256 of the .wasm bytes. The id and version name exactly one binary."
        },
        "size_bytes": { "type": "integer", "minimum": 1, "maximum": 4194304 },
        "source_language": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9+.-]{0,23}$",
          "description": "Informational. The runtime never sees source."
        }
      }
    },
    "facts": {
      "type": "array",
      "uniqueItems": true,
      "maxItems": 64,
      "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.]{0,63}$" },
      "description": "The fact names the step reads. A fact outside this list is not handed to it, and a fact of a classified or local data class is never handed to any step."
    },
    "capabilities": {
      "type": "array",
      "uniqueItems": true,
      "maxItems": 3,
      "items": { "enum": ["facts.read", "decision.emit", "trace.event"] },
      "description": "Closed list. No network, files, clock, randomness, environment or process access can be named, so none can be granted."
    },
    "limits": {
      "type": "object",
      "additionalProperties": false,
      "required": ["fuel", "memory_bytes", "wall_ms"],
      "properties": {
        "fuel": { "type": "integer", "minimum": 1, "maximum": 1000000000 },
        "memory_bytes": { "type": "integer", "minimum": 65536, "maximum": 67108864 },
        "wall_ms": { "type": "integer", "minimum": 1, "maximum": 1000 },
        "output_bytes": { "type": "integer", "minimum": 1, "maximum": 65536 },
        "host_calls": { "type": "integer", "minimum": 0, "maximum": 4096 }
      },
      "description": "Ceilings the host enforces; the platform's own maxima apply on top."
    },
    "metering": {
      "type": "object",
      "additionalProperties": false,
      "required": ["unit"],
      "properties": {
        "unit": { "enum": ["step.eval", "step.fuel_mega"] }
      },
      "description": "Which coordinator unit category an evaluation reports. Accounts' catalogue prices it; the step never does."
    },
    "authoring": {
      "type": "object",
      "additionalProperties": false,
      "required": ["admin_only", "author"],
      "properties": {
        "admin_only": { "const": true },
        "author": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "The verified subject Envoy forwarded, recorded by the service; a request cannot claim another."
        }
      }
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": ["alg", "key_id", "value"],
      "properties": {
        "alg": { "const": "ed25519" },
        "key_id": { "type": "string", "minLength": 1, "maxLength": 128 },
        "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{86}$" }
      },
      "description": "Over the canonical JSON of this document without this field. Absent means unsigned: validates, cannot run."
    }
  }
}