Schema
Use this reference to inspect fields, methods, accepted values and failure outcomes. For setup and working examples, start with the API guide.
Encoding [DEF-E1]
| setting | value | rule |
|---|
escape | minimal | [DEF-E2] |
indent | 2 | [DEF-E3] |
map_keys | utf8-bytes | [DEF-E4] |
numbers | integer-decimal | [DEF-E5] |
opaque | verbatim | [DEF-E6] |
terminator | newline | [DEF-E7] |
duplicate_keys | refuse | [DEF-E8] |
depth_limit | 64 | [DEF-E9] |
Types
| kind | types |
|---|
| built in | bool i32 i64 string |
| declared below | Delegation Envelope Intent Lease Progress Recall Step |
| container [DEF-T3] | list<json> list<string> map<string,json> |
| opaque [DEF-A3] | json |
Named types [DEF-T2]
One spelling is written [DEF-G2] and a wider set is read [DEF-G1]; the width between them is the interoperability guarantee.
| name | is | written | read |
|---|
timestamp | string | rfc3339-micros | rfc3339-wide |
Structs [DEF-T1]
A field is required, or says when it is omitted [DEF-A4]. Each struct says on its own what it does with a field name it has never heard of [DEF-A7]. A wire name never moves; where a language must spell it differently the field says so [DEF-A2].
Step
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | name | string | required | — |
| 2 | ordinal | i32 | required | — |
| 3 | of | i32 | optional · omitted when zero | — |
| 4 | done | i64 | optional · omitted when zero | — |
| 5 | total | i64 | optional · omitted when zero | — |
Progress
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | done | i64 | required | — |
| 2 | total | i64 | optional · omitted when zero | — |
| 3 | updated_at | timestamp | required | — |
| 4 | step | Step | optional · omitted when absent | — |
Recall
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | reason | string | required | — |
| 2 | by | string | optional · omitted when zero | — |
| 3 | at | timestamp | required | — |
| 4 | until | timestamp | required | — |
Lease
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | owner | string | required | — |
| 2 | epoch | i64 | required | — |
| 3 | expires_at | timestamp | required | — |
| 4 | recall | Recall | optional · omitted when absent | — |
Delegation
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | system | string | required | — |
| 2 | external_id | string | required | — |
| 3 | delivered | bool | optional · omitted when zero | — |
Intent
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | want | string | required | — |
| 2 | by | string | optional · omitted when zero | — |
| 3 | at | timestamp | optional · omitted when zero | — |
Envelope
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | schema | string | required | — |
| 2 | actions | list<string> | optional · omitted when zero | — |
Record
the document [DEF-A1] · unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | content | list<string> | required | — |
| 2 | critical | list<string> | optional · omitted when zero | — |
| 3 | id | string | required | — |
| 4 | kind | string | required | — |
| 17 | envelope | Envelope | optional · omitted when absent | — |
| 5 | state | string | required | — |
| 6 | spec | json | required | — |
| 7 | checkpoint | json | optional · omitted when absent | — |
| 8 | progress | Progress | required | — |
| 9 | lease | Lease | required | — |
| 10 | delegation | Delegation | optional · omitted when absent | — |
| 11 | requires | list<string> | optional · omitted when zero | cpp requires_ |
| 12 | error | string | optional · omitted when zero | — |
| 13 | intent | Intent | optional · omitted when absent | — |
| 14 | extensions | map<string,json> | optional · omitted when zero | — |
| 15 | created_at | timestamp | required | — |
| 16 | updated_at | timestamp | required | — |
Request
the protocol request · unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | op | string | required | — |
| 2 | id | string | optional · omitted when zero | — |
| 3 | owner | string | optional · omitted when zero | — |
| 4 | epoch | i64 | optional · omitted when zero | — |
| 5 | ttl_ms | i64 | optional · omitted when zero | — |
| 6 | want | string | optional · omitted when zero | — |
| 7 | by | string | optional · omitted when zero | — |
| 8 | reason | string | optional · omitted when zero | — |
| 9 | record | json | optional · omitted when zero | — |
| 10 | base | json | optional · omitted when zero | — |
Response
the protocol response · unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | kind | string | optional · omitted when zero | — |
| 2 | error | string | optional · omitted when zero | — |
| 3 | id | string | optional · omitted when zero | — |
| 4 | record | json | optional · omitted when zero | — |
| 5 | records | list<json> | optional · omitted when zero | — |
| 6 | bool | bool | optional · omitted when zero | cpp bool_ |
| 7 | unreadable | list<string> | optional · omitted when zero | — |
Enumerations [DEF-T5]
An enumeration is a closed vocabulary of wire names, and each one says on its own what a reader does with a member it has never heard of [DEF-A5].
Capability
a member this reader does not know is grant
| id | member | wire | assurance |
|---|
| 1 | resume | resume | falsifiable |
| 2 | survives_process_exit | survives_process_exit | recovered |
| 3 | verifies_content | verifies_content | checked |
| 4 | delegates | delegates | trusted |
Verdict
a member this reader does not know is grant
| id | member | wire | transcript |
|---|
| 1 | not_found | not_found | — |
| 2 | lease_held | lease_held | — |
| 3 | stale_epoch | stale_epoch | — |
| 4 | conflict | conflict | refused |
| 5 | lease_expired | lease_expired | — |
| 6 | terminal | terminal | — |
| 7 | invalid | invalid | — |
| 8 | unknown_schema | unknown_schema | — |
| 9 | unknown_op | unknown_op | refused |
| 10 | not_supported | not_supported | refused |
| 11 | other | other | refused |
Vocabulary Content [DEF-A8]
declared of Record · carried in content · the subset a reader must know in critical
| id | term | present when | critical marking stripped |
|---|
| 1 | abstraction.job/base@1 | always | — |
| 2 | abstraction.job/intent@1 | intent is present | — |
| 3 | abstraction.download/ranges@1 | checkpoint.verified is a member of the opaque value, and not null | true |
| 4 | abstraction.job/delegation@1 | delegation is present | — |
| 5 | abstraction.job/envelope@1 | envelope is present | — |
| 6 | abstraction.job/terminal@1 | state is one of complete, failed, cancelled | — |
| 7 | abstraction.job/recall@1 | lease.recall is present | — |
| 8 | abstraction.job/step@1 | progress.step is present | true |
Refusal words [DEF-R1]
| order | word | stage |
|---|
| 1 | malformed | grammar |
| 2 | bad_string | grammar |
| 3 | number_spelling | grammar |
| 4 | wrong_type | grammar |
| 5 | bad_timestamp | grammar |
| 6 | depth_exceeded | grammar |
| 7 | duplicate_key | grammar |
| 8 | duplicate_field | structure |
| 9 | unknown_field | structure |
| 10 | missing_field | structure |
| 11 | trailing_bytes | document |
| 12 | unknown_critical | derivation |
| 13 | not_a_subset | derivation |
| 14 | content_mismatch | derivation |
Protocol Store [DEF-P1]
request Request · response Response · the operation in op · the verdict in kind from Verdict · an operation this peer does not know is unknown_op
| id | operation |
|---|
| 1 | submit |
| 2 | load |
| 3 | list |
| 4 | orphans |
| 5 | claimable |
| 6 | claim |
| 7 | renew |
| 8 | release |
| 9 | set_intent |
| 10 | recall |
| 11 | write |