Schema · atlas/proof

Atlas fact with its proof

GetFact's answer (RFC 0086, proto iohr.atlas.v1.GetFactResponse): one fact and its proof tree, why Atlas believes it down to evidence, whether every leaf rests on evidence and the longest chain to it. Only a complete proof may be shown to a person as a reason. The fact is https://schemas.inorbit.hr/atlas/fact/v0.json; a validator loads both. Every node names claims, rules and evidence by id and nothing else; every object is closed. Fields the API leaves at their default (an empty string, false, 0, an empty list) may be absent. Draft line: it may still be corrected.

Canonical $id, draft

https://schemas.inorbit.hr/atlas/proof/v0.json

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/atlas/proof/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.

factanyrequired
The fact.
proofanyrequired
Why Atlas believes it: the fact's own node, its inputs below it.
completebooleanoptional
Every leaf of the proof rests on evidence.
depthintegeroptional
The longest chain from the fact to evidence; 0 for a base claim.
0 to 64

03Examples

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

{
  "fact": {
    "id": "clm_1c2d3e4f-6a7b-4c8d-9e0f-2a3b4c5d6e7f",
    "subject": "ent_3e4f5a6b-8c9d-4e0f-9a1b-4c5d6e7f8091",
    "predicate": "net.egress@2",
    "value": "443",
    "polarity": "absent",
    "class": "absence",
    "support": "observed",
    "validity": "current",
    "conflict": "none",
    "evidence": [
      {
        "type": "observation",
        "id": "obv_6b7c8d9e-1f2a-4b3c-8d4e-7f8091a2b3c4"
      }
    ]
  },
  "proof": {
    "claim_id": "clm_1c2d3e4f-6a7b-4c8d-9e0f-2a3b4c5d6e7f",
    "kind": "base",
    "evidence": [
      {
        "type": "observation",
        "id": "obv_6b7c8d9e-1f2a-4b3c-8d4e-7f8091a2b3c4"
      }
    ]
  }
}

The repository's tests also check 7 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/proof/v0.json" }
]

check-jsonschema

check-jsonschema --schemafile https://schemas.inorbit.hr/atlas/proof/v0.json my-file.json

ajv-cli

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

curl

curl -s https://schemas.inorbit.hr/atlas/proof/v0.json

05The schema itself

The raw file of v0, as published.

schemas.inorbit.hr/atlas/proof/v0.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.inorbit.hr/atlas/proof/v0.json",
  "title": "Atlas fact with its proof",
  "description": "GetFact's answer (RFC 0086, proto iohr.atlas.v1.GetFactResponse): one fact and its proof tree, why Atlas believes it down to evidence, whether every leaf rests on evidence and the longest chain to it. Only a complete proof may be shown to a person as a reason. The fact is https://schemas.inorbit.hr/atlas/fact/v0.json; a validator loads both. Every node names claims, rules and evidence by id and nothing else; every object is closed. Fields the API leaves at their default (an empty string, false, 0, an empty list) may be absent. Draft line: it may still be corrected.",
  "type": "object",
  "additionalProperties": false,
  "required": ["fact", "proof"],
  "properties": {
    "fact": {
      "description": "The fact.",
      "$ref": "https://schemas.inorbit.hr/atlas/fact/v0.json"
    },
    "proof": {
      "description": "Why Atlas believes it: the fact's own node, its inputs below it.",
      "$ref": "#/$defs/node"
    },
    "complete": {
      "description": "Every leaf of the proof rests on evidence.",
      "type": "boolean"
    },
    "depth": {
      "description": "The longest chain from the fact to evidence; 0 for a base claim.",
      "type": "integer",
      "minimum": 0,
      "maximum": 64
    }
  },
  "$defs": {
    "node": {
      "description": "One claim in a proof (proto iohr.atlas.v1.ProofNode): a derived claim names its rule and inputs, a base claim its evidence.",
      "type": "object",
      "additionalProperties": false,
      "required": ["claim_id", "kind"],
      "properties": {
        "claim_id": {
          "description": "The claim: clm_ and a UUID.",
          "$ref": "https://schemas.inorbit.hr/atlas/fact/v0.json#/$defs/claim_id"
        },
        "kind": {
          "description": "derived or base.",
          "enum": ["derived", "base"]
        },
        "rule": {
          "description": "The rule and version that derived it; empty for a base claim.",
          "$ref": "https://schemas.inorbit.hr/atlas/fact/v0.json#/$defs/rule"
        },
        "inputs": {
          "description": "Why each input is believed; empty for a base claim.",
          "type": "array",
          "maxItems": 64,
          "items": { "$ref": "#/$defs/node" }
        },
        "evidence": {
          "description": "The evidence a base claim rests on; empty for a derived one.",
          "type": "array",
          "maxItems": 256,
          "items": { "$ref": "https://schemas.inorbit.hr/atlas/fact/v0.json#/$defs/evidence_ref" }
        }
      },
      "if": { "properties": { "kind": { "const": "derived" } } },
      "then": {
        "required": ["rule", "inputs"],
        "properties": { "rule": { "minLength": 1 }, "inputs": { "minItems": 1 }, "evidence": { "maxItems": 0 } }
      },
      "else": {
        "properties": { "rule": { "maxLength": 0 }, "inputs": { "maxItems": 0 } }
      }
    }
  }
}