Sign in

← All schemas

Schema · atlas/decided

Atlas decided world

The decided world Atlas derives against (RFC 0086, ADR 0023, PRD 0152): the typed decisions the accepted ADRs and RFCs state, as atlas-derive reads them (crates/atlas-derive/src/exit/decided.rs, the Decision type). A list of decisions, in file order. A decision comes only from a fenced decided block of [[decided]] tables (subject, predicate, text) in a document whose front matter says kind adr or rfc and whose status is accepted, approved or decided; prose is never typed and a proposal decides nothing. A decision names its document and the digest of its bytes, the lines of its block, the document's title, the subject, the predicate and the value, and nothing else: no note (the words a block quotes), no prose, no comment, no author. The bounds are the reader's: a decision that does not fit is not read. Every object is closed. Draft line: it may still be corrected.

Canonical $id, draft
https://schemas.inorbit.hr/atlas/decided/v0.json
01Versions

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

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.

    03Examples

    Valid documents with made-up values, as the repository's tests check them.

    []

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

    04Check a file against it

    Replace the file name with yours.

    VS Code, JetBrains: settings
    "json.schemas": [
      { "fileMatch": ["my-file.json"], "url": "https://schemas.inorbit.hr/atlas/decided/v0.json" }
    ]
    check-jsonschema
    check-jsonschema --schemafile https://schemas.inorbit.hr/atlas/decided/v0.json my-file.json
    ajv-cli
    ajv validate --spec=draft2020 -s <(curl -s https://schemas.inorbit.hr/atlas/decided/v0.json) -d my-file.json
    curl
    curl -s https://schemas.inorbit.hr/atlas/decided/v0.json
    05The schema itself

    The raw file of v0, as published.

    schemas.inorbit.hr/atlas/decided/v0.json
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "$id": "https://schemas.inorbit.hr/atlas/decided/v0.json",
      "title": "Atlas decided world",
      "description": "The decided world Atlas derives against (RFC 0086, ADR 0023, PRD 0152): the typed decisions the accepted ADRs and RFCs state, as atlas-derive reads them (crates/atlas-derive/src/exit/decided.rs, the Decision type). A list of decisions, in file order. A decision comes only from a fenced decided block of [[decided]] tables (subject, predicate, text) in a document whose front matter says kind adr or rfc and whose status is accepted, approved or decided; prose is never typed and a proposal decides nothing. A decision names its document and the digest of its bytes, the lines of its block, the document's title, the subject, the predicate and the value, and nothing else: no note (the words a block quotes), no prose, no comment, no author. The bounds are the reader's: a decision that does not fit is not read. Every object is closed. Draft line: it may still be corrected.",
      "type": "array",
      "maxItems": 4096,
      "items": {
        "$ref": "#/$defs/decision"
      },
      "$defs": {
        "decision": {
          "description": "One decision a document states (atlas-derive exit::decided::Decision).",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "source",
            "digest",
            "lines",
            "title",
            "subject",
            "predicate",
            "text"
          ],
          "properties": {
            "source": {
              "description": "The document: its file name in the decided directory, a Markdown file. Never a path.",
              "type": "string",
              "maxLength": 255,
              "pattern": "^[^/\\\\\\u0000-\\u001f\\u007f]+\\.md$"
            },
            "digest": {
              "description": "sha256: and 64 lowercase hex digits: the SHA-256 of the document's bytes as read, so a reader can see which bytes the decision came from. The exit report cites it on the decided side of a contradiction.",
              "type": "string",
              "pattern": "^sha256:[0-9a-f]{64}$"
            },
            "lines": {
              "description": "The lines that state it, one-based and inclusive: the [[decided]] line first, the last line before the next table or the closing fence last. The first is never after the last.",
              "type": "array",
              "prefixItems": [
                {
                  "type": "integer",
                  "minimum": 1
                },
                {
                  "type": "integer",
                  "minimum": 1
                }
              ],
              "items": false,
              "minItems": 2,
              "maxItems": 2
            },
            "title": {
              "description": "The document's title from its front matter; the file name when it has none or one longer than 300 bytes.",
              "type": "string",
              "maxLength": 300,
              "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
            },
            "subject": {
              "description": "What it is about: a service or deployment name, as the observers name it (deployment/tbd/paging).",
              "$ref": "#/$defs/token",
              "maxLength": 256
            },
            "predicate": {
              "description": "The predicate without a namespace (egress_only, depends_on).",
              "$ref": "#/$defs/token",
              "maxLength": 64
            },
            "text": {
              "description": "The value as written (host:port,host:port; an entity name). A value names, it does not quote: it is the block's text key, or its value key, and never the note.",
              "$ref": "#/$defs/token",
              "maxLength": 2048
            }
          }
        },
        "token": {
          "description": "A string a block can hold between its quotes: no double quote, no control character.",
          "type": "string",
          "pattern": "^[^\"\\u0000-\\u001f\\u007f]*$"
        }
      }
    }