Schema · atlas/observer

Atlas observer

A source of evidence as Atlas keeps it (RFC 0086, ADR 0006): its id, its class, what it is and which version of it. The class says what kind of operation produced its output (a measurement, a deterministic reading, a model's interpretation, a person's answer, another system's statement), and the proof rules treat the classes differently. The shape of tbd_atlas_core::observer::Observer, with its id written as the API writes every Atlas id: obs_ and a UUID, never a bare UUID. An observer is a name and a version, never a credential, a prompt or a document's text; the object is closed so a field outside these is refused. The tenant (account and Decisions space) is the store's scope, not a field of the observer. Draft line: it may still be corrected.

Canonical $id, draft

https://schemas.inorbit.hr/atlas/observer/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/observer/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.

idanyrequired
The observer's id: obs_ and a UUID.
classanyrequired
What kind of operation it performs. A sensor's readings come from a direct_sensor.
namestringrequired
What it is: 1 to 128 of letters, digits and . _ : / -, no spaces (k8s-reader, envoy-route-reader, ebpf-capture). A name, never a sentence.
pattern ^[A-Za-z0-9._:/-]{1,128}$
versionstringrequired
Its version: 1 to 64 of letters, digits and . _ + -. A new version stales its calibration.
pattern ^[A-Za-z0-9._+-]{1,64}$

03Examples

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

{
  "id": "obs_0192b8a4-5c3e-7d21-9f4a-7c8d9e0f1a2b",
  "class": "deterministic_extractor",
  "name": "k8s-reader",
  "version": "0.3.1+build.7"
}

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

check-jsonschema

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

ajv-cli

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

curl

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

05The schema itself

The raw file of v0, as published.

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.inorbit.hr/atlas/observer/v0.json",
  "title": "Atlas observer",
  "description": "A source of evidence as Atlas keeps it (RFC 0086, ADR 0006): its id, its class, what it is and which version of it. The class says what kind of operation produced its output (a measurement, a deterministic reading, a model's interpretation, a person's answer, another system's statement), and the proof rules treat the classes differently. The shape of tbd_atlas_core::observer::Observer, with its id written as the API writes every Atlas id: obs_ and a UUID, never a bare UUID. An observer is a name and a version, never a credential, a prompt or a document's text; the object is closed so a field outside these is refused. The tenant (account and Decisions space) is the store's scope, not a field of the observer. Draft line: it may still be corrected.",
  "type": "object",
  "additionalProperties": false,
  "required": ["id", "class", "name", "version"],
  "properties": {
    "id": {
      "description": "The observer's id: obs_ and a UUID.",
      "$ref": "#/$defs/observer_id"
    },
    "class": {
      "description": "What kind of operation it performs. A sensor's readings come from a direct_sensor.",
      "$ref": "#/$defs/observer_class"
    },
    "name": {
      "description": "What it is: 1 to 128 of letters, digits and . _ : / -, no spaces (k8s-reader, envoy-route-reader, ebpf-capture). A name, never a sentence.",
      "type": "string",
      "pattern": "^[A-Za-z0-9._:/-]{1,128}$"
    },
    "version": {
      "description": "Its version: 1 to 64 of letters, digits and . _ + -. A new version stales its calibration.",
      "type": "string",
      "pattern": "^[A-Za-z0-9._+-]{1,64}$"
    }
  },
  "$defs": {
    "observer_id": {
      "description": "An observer's id: obs_ and a UUID.",
      "type": "string",
      "maxLength": 40,
      "pattern": "^obs_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "observer_class": {
      "description": "The observer classes (tbd_atlas_core::observer::ObserverClass, as the API writes them). direct_sensor measures the world; deterministic_extractor reads an artefact with a program (same input, same output); model_extractor is a model's reading, which interprets and never measures; human_testimony is a person's answer; external_system is another system's statement through its API.",
      "enum": [
        "direct_sensor",
        "deterministic_extractor",
        "model_extractor",
        "human_testimony",
        "external_system"
      ]
    }
  }
}