Sign in
InOrbit

← All schemas

Schema · atlas/fact

Atlas fact

One fact as Atlas currently believes it (RFC 0086): a claim about a subject, its support, whether it is still current, whether evidence contradicts it, and what it rests on. The shape of each item in ListFacts and ListContradictions and of GetFact's fact (proto iohr.atlas.v1.Fact, JSON field names as the API writes them). A fact names entities, predicates and evidence by id; it never carries a document's text, a prompt or a credential, and the object is closed so a field outside these is refused. Fields the API leaves at their default (an empty string, false, an empty list) may be absent. Draft line: it may still be corrected.

Canonical $id, draft
https://schemas.inorbit.hr/atlas/fact/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.

  • idanyrequired

    The claim's id: clm_ and a UUID.

  • subjectstringrequired

    What it is about: an entity id, ent_ and a UUID.

    pattern ^ent_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$at most 40 characters

  • predicatestringrequired

    What it says of the subject: the predicate and its vocabulary version, name@version (depends_on@1). The name is dotted lowercase parts, at most 64 characters.

    pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*@[0-9]{1,10}$at least 3 charactersat most 75 characters

  • valuestringoptional

    The value written out: an entity as its id (ent_ and a UUID), text as it is, a whole number, true or false, a digest's hex, or a duration as its milliseconds. The predicate says which. Short by design: a value names, it does not quote.

    at most 1024 characters

  • polarityenumrequired

    holds, or absent: the statement says something is not there (ADR 0010).

    One of"holds""absent"

  • classenumrequired

    The claim class.

    One of"existence""identity""dependency""user_outcome""temporal""absence""causal""security""compliance_control""architectural_invariant""release_property"

  • supportenumrequired

    How well evidence supports it.

    One of"none""observed""supported""verified"

  • validityenumrequired

    current, stale or expired. Stale is not false (ADR 0003).

    One of"current""stale""expired"

  • stale_sincestringoptional

    When it went stale, RFC 3339 in UTC with milliseconds; empty unless stale.

    pattern ^$|^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$at most 40 characters

  • stale_changestringoptional

    The change that made it stale, chg_ and a UUID; empty unless stale.

    pattern ^$|^chg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$at most 40 characters

  • conflictenumrequired

    Whether evidence contradicts it. A contradicted fact keeps its own support: both sides are shown.

    One of"none""contradicted"

  • contradicted_bylist of anyoptional

    The evidence that contradicts it; empty unless contradicted.

    at most 256 items

  • derivedbooleanoptional

    Whether a rule derived it from other claims.

  • ruleanyoptional

    The rule and its version (dependency_transitivity@1); empty when not derived.

  • inputslist of anyoptional

    The claims it was derived from; empty when not derived.

    at most 256 itemsno repeats

  • evidencelist of anyoptional

    The evidence it rests on directly.

    at most 256 items

03Examples

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

{
  "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"
}

The repository's tests also check 14 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/fact/v0.json" }
]
check-jsonschema
check-jsonschema --schemafile https://schemas.inorbit.hr/atlas/fact/v0.json my-file.json
ajv-cli
ajv validate --spec=draft2020 -s <(curl -s https://schemas.inorbit.hr/atlas/fact/v0.json) -d my-file.json
curl
curl -s https://schemas.inorbit.hr/atlas/fact/v0.json
05The schema itself

The raw file of v0, as published.

schemas.inorbit.hr/atlas/fact/v0.json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.inorbit.hr/atlas/fact/v0.json",
  "title": "Atlas fact",
  "description": "One fact as Atlas currently believes it (RFC 0086): a claim about a subject, its support, whether it is still current, whether evidence contradicts it, and what it rests on. The shape of each item in ListFacts and ListContradictions and of GetFact's fact (proto iohr.atlas.v1.Fact, JSON field names as the API writes them). A fact names entities, predicates and evidence by id; it never carries a document's text, a prompt or a credential, and the object is closed so a field outside these is refused. Fields the API leaves at their default (an empty string, false, an empty list) may be absent. Draft line: it may still be corrected.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "subject",
    "predicate",
    "polarity",
    "class",
    "support",
    "validity",
    "conflict"
  ],
  "properties": {
    "id": {
      "description": "The claim's id: clm_ and a UUID.",
      "$ref": "#/$defs/claim_id"
    },
    "subject": {
      "description": "What it is about: an entity id, ent_ and a UUID.",
      "type": "string",
      "maxLength": 40,
      "pattern": "^ent_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "predicate": {
      "description": "What it says of the subject: the predicate and its vocabulary version, name@version (depends_on@1). The name is dotted lowercase parts, at most 64 characters.",
      "type": "string",
      "minLength": 3,
      "maxLength": 75,
      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*@[0-9]{1,10}$"
    },
    "value": {
      "description": "The value written out: an entity as its id (ent_ and a UUID), text as it is, a whole number, true or false, a digest's hex, or a duration as its milliseconds. The predicate says which. Short by design: a value names, it does not quote.",
      "type": "string",
      "maxLength": 1024
    },
    "polarity": {
      "description": "holds, or absent: the statement says something is not there (ADR 0010).",
      "enum": [
        "holds",
        "absent"
      ]
    },
    "class": {
      "description": "The claim class.",
      "enum": [
        "existence",
        "identity",
        "dependency",
        "user_outcome",
        "temporal",
        "absence",
        "causal",
        "security",
        "compliance_control",
        "architectural_invariant",
        "release_property"
      ]
    },
    "support": {
      "description": "How well evidence supports it.",
      "enum": [
        "none",
        "observed",
        "supported",
        "verified"
      ]
    },
    "validity": {
      "description": "current, stale or expired. Stale is not false (ADR 0003).",
      "enum": [
        "current",
        "stale",
        "expired"
      ]
    },
    "stale_since": {
      "description": "When it went stale, RFC 3339 in UTC with milliseconds; empty unless stale.",
      "type": "string",
      "maxLength": 40,
      "pattern": "^$|^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$"
    },
    "stale_change": {
      "description": "The change that made it stale, chg_ and a UUID; empty unless stale.",
      "type": "string",
      "maxLength": 40,
      "pattern": "^$|^chg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "conflict": {
      "description": "Whether evidence contradicts it. A contradicted fact keeps its own support: both sides are shown.",
      "enum": [
        "none",
        "contradicted"
      ]
    },
    "contradicted_by": {
      "description": "The evidence that contradicts it; empty unless contradicted.",
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/evidence_ref"
      }
    },
    "derived": {
      "description": "Whether a rule derived it from other claims.",
      "type": "boolean"
    },
    "rule": {
      "description": "The rule and its version (dependency_transitivity@1); empty when not derived.",
      "$ref": "#/$defs/rule"
    },
    "inputs": {
      "description": "The claims it was derived from; empty when not derived.",
      "type": "array",
      "maxItems": 256,
      "uniqueItems": true,
      "items": {
        "$ref": "#/$defs/claim_id"
      }
    },
    "evidence": {
      "description": "The evidence it rests on directly.",
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/evidence_ref"
      }
    }
  },
  "allOf": [
    {
      "if": {
        "required": [
          "validity"
        ],
        "properties": {
          "validity": {
            "const": "stale"
          }
        }
      },
      "then": {
        "required": [
          "stale_since",
          "stale_change"
        ],
        "properties": {
          "stale_since": {
            "minLength": 1
          },
          "stale_change": {
            "minLength": 1
          }
        }
      },
      "else": {
        "properties": {
          "stale_since": {
            "maxLength": 0
          },
          "stale_change": {
            "maxLength": 0
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "conflict"
        ],
        "properties": {
          "conflict": {
            "const": "contradicted"
          }
        }
      },
      "then": {
        "required": [
          "contradicted_by"
        ],
        "properties": {
          "contradicted_by": {
            "minItems": 1
          }
        }
      },
      "else": {
        "properties": {
          "contradicted_by": {
            "maxItems": 0
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "derived"
        ],
        "properties": {
          "derived": {
            "const": true
          }
        }
      },
      "then": {
        "required": [
          "rule",
          "inputs"
        ],
        "properties": {
          "rule": {
            "minLength": 1
          },
          "inputs": {
            "minItems": 1
          }
        }
      },
      "else": {
        "properties": {
          "rule": {
            "maxLength": 0
          },
          "inputs": {
            "maxItems": 0
          }
        }
      }
    }
  ],
  "$defs": {
    "claim_id": {
      "type": "string",
      "pattern": "^clm_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "rule": {
      "type": "string",
      "maxLength": 128,
      "pattern": "^$|^[a-z][a-z0-9_]*@[0-9]+$"
    },
    "evidence_ref": {
      "description": "A piece of evidence by kind and id (proto iohr.atlas.v1.EvidenceRef). Only the reference: the evidence itself is read with the caller's rights.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "id"
      ],
      "properties": {
        "type": {
          "description": "The evidence's kind.",
          "enum": [
            "observation",
            "artifact",
            "extraction",
            "testimony",
            "claim"
          ]
        },
        "id": {
          "description": "Its id, prefixed by its kind (obv_, art_, ext_, tst_ or clm_) and a UUID.",
          "type": "string",
          "pattern": "^(obv|art|ext|tst|clm)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "type": {
                "const": "observation"
              }
            }
          },
          "then": {
            "properties": {
              "id": {
                "pattern": "^obv_"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "artifact"
              }
            }
          },
          "then": {
            "properties": {
              "id": {
                "pattern": "^art_"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "extraction"
              }
            }
          },
          "then": {
            "properties": {
              "id": {
                "pattern": "^ext_"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "testimony"
              }
            }
          },
          "then": {
            "properties": {
              "id": {
                "pattern": "^tst_"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "claim"
              }
            }
          },
          "then": {
            "properties": {
              "id": {
                "pattern": "^clm_"
              }
            }
          }
        }
      ]
    }
  }
}