causalontology 2.0.0 → 4.0.0

data/lib/causalontology/spec/schema/continuant.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/continuant.schema.json",
+  "title": "Continuant",
+  "type": "object",
+  "required": [
+    "id",
+    "label",
+    "category"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^continuant:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "continuant"
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "canonical label, same discipline as occurrents; homonyms by qualification (bat_animal, bat_club)"
+    },
+    "category": {
+      "enum": [
+        "object",
+        "agent",
+        "place",
+        "substance",
+        "collection",
+        "information"
+      ],
+      "description": "REQUIRED and CLOSED; extending this enumeration is a MAJOR version change"
+    }
+  }
+}

data/lib/causalontology/spec/schema/cross_stratal_seam.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/cross_stratal_seam.schema.json",
+  "title": "Cross Stratal Seam",
+  "description": "3.0.0. A first-class MANAGED record of a legitimate jump across NON-ADJACENT strata. Where the Causal Relation Object's boolean 'skips' flag can only assert THAT a relation crosses non-adjacent strata, a Cross Stratal Seam records HOW HONEST that jump is: its mechanism_status distinguishes 'a mechanism exists but is deliberately unmodeled here' from 'no mechanism exists', and an optional chain draws the intervening adjacent-stratum pathway. Its HOME is the coarsest stratum it touches (the endpoint of greater ordinal), which a layer-to-stratum binding can check. The 'skips' boolean is SUBORDINATED to this construct: a bare skipping Causal Relation Object remains valid and is the coarse, mechanism-status-unspecified form.",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "source",
+    "target",
+    "mechanism_status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^cross_stratal_seam:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "cross_stratal_seam"
+    },
+    "source": {
+      "type": "string",
+      "pattern": "^occurrent:[0-9a-f]{64}$",
+      "description": "one endpoint occurrent of the seam; its stratum ordinal is one end of the jump"
+    },
+    "target": {
+      "type": "string",
+      "pattern": "^occurrent:[0-9a-f]{64}$",
+      "description": "the other endpoint occurrent of the seam; its stratum ordinal is the other end of the jump"
+    },
+    "mechanism_status": {
+      "enum": [
+        "unmodeled",
+        "absent"
+      ],
+      "description": "the HONEST-IGNORANCE distinction. 'unmodeled': an intervening mechanism EXISTS across the skipped strata but is deliberately not drawn here. 'absent': there is genuinely NO intervening mechanism - the jump is direct. This is exactly what the boolean skips flag could not say."
+    },
+    "chain": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^occurrent:[0-9a-f]{64}$"
+      },
+      "description": "OPTIONAL. The intervening pathway DRAWN as an ordered list of occurrents at INTERVENING strata (each strictly between the two endpoints' stratum ordinals, same scheme, strictly monotone from one endpoint toward the other). When present the seam is DRAWN, so its mechanism_status must be 'unmodeled', never 'absent' (a drawn mechanism is not absent)."
+    }
+  }
+}

data/lib/causalontology/spec/schema/enrichment.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/enrichment.schema.json",
+  "title": "Enrichment",
+  "type": "object",
+  "required": [
+    "id",
+    "about",
+    "field",
+    "entry",
+    "source",
+    "timestamp"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^enrichment:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "enrichment"
+    },
+    "about": {
+      "type": "string",
+      "pattern": "^(occurrent|continuant|realizable):[0-9a-f]{64}$",
+      "description": "the content object being enriched (Causal Relation Objects are never enriched in place - they are refined)"
+    },
+    "field": {
+      "enum": [
+        "aliases",
+        "participants",
+        "subsumes",
+        "part_of",
+        "realized_in",
+        "occurrent_subsumes",
+        "occurrent_part_of"
+      ],
+      "description": "field-to-kind validity is fixed by semantics.md rule 12 (amended in 2.0.0: two occurrent forms added)"
+    },
+    "entry": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "lang",
+            "text"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "lang": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "description": "the entry shape for the aliases field (lang is a BCP 47 language tag)"
+        },
+        {
+          "type": "string",
+          "pattern": "^(occurrent|continuant):[0-9a-f]{64}$",
+          "description": "the entry shape for the reference fields, checked per field by semantics.md rule 12"
+        }
+      ]
+    },
+    "source": {
+      "type": "string",
+      "pattern": "^ed25519:[0-9a-f]{64}$"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{128}$"
+    }
+  }
+}

data/lib/causalontology/spec/schema/individual.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/individual.schema.json",
+  "title": "Token Individual",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "instantiates"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^token_individual:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "token_individual"
+    },
+    "instantiates": {
+      "type": "string",
+      "pattern": "^continuant:[0-9a-f]{64}$",
+      "description": "the continuant TYPE of which this is an instance; MANDATORY (P1)"
+    },
+    "designator": {
+      "type": "string",
+      "minLength": 1,
+      "description": "an OPAQUE local designator distinguishing this individual from others of its type. SEE THE PRIVACY REQUIREMENT, N5.1.3 / spec/safety.md."
+    },
+    "part_of": {
+      "type": "string",
+      "pattern": "^token_individual:[0-9a-f]{64}$",
+      "description": "optional: the particular individual of which this is a part (TOKEN mereology)"
+    }
+  }
+}

data/lib/causalontology/spec/schema/occurrent.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/occurrent.schema.json",
+  "title": "Occurrent",
+  "type": "object",
+  "required": [
+    "id",
+    "label",
+    "category"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^occurrent:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "occurrent"
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "canonical label: English, lowercase snake_case, whole words (press_button, light_on); homonyms disambiguated by qualification (charge_battery, charge_attack)"
+    },
+    "category": {
+      "enum": [
+        "action",
+        "event",
+        "process",
+        "state",
+        "state_change"
+      ],
+      "description": "REQUIRED and CLOSED so identity inputs are deterministic; extending this enumeration is a MAJOR version change (GOVERNANCE.md)"
+    },
+    "stratum": {
+      "type": "string",
+      "pattern": "^stratum:[0-9a-f]{64}$",
+      "description": "OPTIONAL, IDENTITY-BEARING: the level of description at which this occurrent is pitched (2.0.0 N3.3)"
+    }
+  }
+}

data/lib/causalontology/spec/schema/port.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/port.schema.json",
+  "title": "Port",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "bearer",
+    "label",
+    "direction",
+    "accepts"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^port:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "port"
+    },
+    "bearer": {
+      "type": "string",
+      "pattern": "^continuant:[0-9a-f]{64}$",
+      "description": "the continuant TYPE that has this interface"
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "the name of the interface (for example: perforant_path, fornix)"
+    },
+    "direction": {
+      "enum": [
+        "in",
+        "out",
+        "bidirectional"
+      ]
+    },
+    "accepts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^occurrent:[0-9a-f]{64}$"
+      },
+      "description": "the kinds of occurrent this port accepts (direction in) or emits (direction out) or both (bidirectional)"
+    },
+    "realizable": {
+      "type": "string",
+      "pattern": "^realizable:[0-9a-f]{64}$",
+      "description": "optional: the disposition, function, or role this port serves"
+    }
+  }
+}

data/lib/causalontology/spec/schema/predicted_occurrence.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/predicted_occurrence.schema.json",
+  "title": "Predicted Occurrence",
+  "description": "4.0.0. A first-class record of an EXPECTATION: an occurrent type predicted, by a stated predictor, to occur over a stated window. A prediction is NOT an assertion that the thing happened - it is the sibling of the token_occurrence that has not (yet) happened, and it satisfies no rule that requires a token_occurrence (Rule 24). Its interval MUST carry exactly ONE temporal dimension: a wall-clock start (with optional end) or an ordinal start_tick (with optional end_tick), never both and never neither. The optional strength is the predicted probability - part of the PREDICTED CONTENT itself, identity-bearing when present, not a provenance evaluation (the narrow, deliberate 4.0.0 extension of Principle P4).",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "instantiates",
+    "interval",
+    "predictor"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^predicted_occurrence:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "predicted_occurrence"
+    },
+    "instantiates": {
+      "type": "string",
+      "pattern": "^occurrent:[0-9a-f]{64}$",
+      "description": "the occurrent TYPE predicted to occur; MANDATORY (P1)"
+    },
+    "interval": {
+      "$ref": "#/$defs/predicted_interval"
+    },
+    "predictor": {
+      "type": "string",
+      "pattern": "^(continuant|token_individual):[0-9a-f]{64}$",
+      "description": "the predicting source - a MODELED agent or construct inside the ontology (a continuant type or a particular token individual), never a cryptographic key"
+    },
+    "strength": {
+      "type": "number",
+      "description": "OPTIONAL, identity-bearing when present: the predicted probability, part of the predicted content itself, NOT a provenance evaluation (4.0.0 Locked Decision extension of Principle P4)"
+    }
+  },
+  "$defs": {
+    "predicted_interval": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time",
+          "description": "RFC 3339, UTC, mandatory Z suffix - the wall-clock dimension"
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "start_tick": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "the ordinal dimension: a discrete tick with NO wall-clock mapping (Rule 23)"
+        },
+        "end_tick": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "description": "the predicted window. Rule 24 enforces exactly ONE temporal dimension: start (wall-clock, optional end) or start_tick (ordinal, optional end_tick), never both (dimension_conflict, HARD) and never neither (missing_dimension, HARD)"
+    }
+  }
+}

data/lib/causalontology/spec/schema/prediction_error.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/prediction_error.schema.json",
+  "title": "Prediction Error",
+  "description": "4.0.0. The first-class record of how a prediction met the world: the graded discrepancy between a predicted_occurrence and what was - or was not - observed. When observed is present it names the token_occurrence that answered the prediction and MUST instantiate the same occurrent the prediction instantiates (Rule 24, pairing_mismatch, HARD); when observed is ABSENT the predicted occurrence was not fulfilled by any recorded occurrence. discrepancy reads actual minus expected: positive = exceeded expectation, negative = fell short, zero = fulfilled.",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "predicted",
+    "discrepancy"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^prediction_error:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "prediction_error"
+    },
+    "predicted": {
+      "type": "string",
+      "pattern": "^predicted_occurrence:[0-9a-f]{64}$",
+      "description": "the prediction this error grades; MANDATORY - an error without a prediction is not an error"
+    },
+    "observed": {
+      "type": "string",
+      "pattern": "^token_occurrence:[0-9a-f]{64}$",
+      "description": "OPTIONAL: the token occurrence that answered the prediction. ABSENT means the predicted occurrence was not fulfilled by any recorded occurrence - the surprise of nothing arriving"
+    },
+    "discrepancy": {
+      "type": "number",
+      "description": "signed, graded; actual minus expected - positive = exceeded expectation, negative = fell short, zero = fulfilled (the comparator sign convention)"
+    }
+  }
+}

data/lib/causalontology/spec/schema/quality.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/quality.schema.json",
+  "title": "Quality",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "label",
+    "datatype"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^quality:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "quality"
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "for example: cortisol_concentration, membrane_potential, mass"
+    },
+    "datatype": {
+      "enum": [
+        "quantity",
+        "categorical",
+        "boolean"
+      ]
+    },
+    "unit": {
+      "type": "string",
+      "description": "the canonical UCUM unit code; REQUIRED when datatype is quantity, and MUST be absent otherwise"
+    },
+    "stratum": {
+      "type": "string",
+      "pattern": "^stratum:[0-9a-f]{64}$",
+      "description": "optional: the level of description at which this quality is defined"
+    }
+  }
+}

data/lib/causalontology/spec/schema/realizable.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/realizable.schema.json",
+  "title": "Realizable Entity",
+  "type": "object",
+  "required": [
+    "id",
+    "kind",
+    "bearer"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^realizable:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "realizable"
+    },
+    "kind": {
+      "enum": [
+        "disposition",
+        "function",
+        "role"
+      ]
+    },
+    "bearer": {
+      "type": "string",
+      "pattern": "^continuant:[0-9a-f]{64}$"
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "OPTIONAL, IDENTITY-BEARING: the name of this disposition, function, or role. Repairs the 1.0.0 identity collision that limited a bearer to one realizable per kind (2.0.0 4.3)"
+    }
+  }
+}

data/lib/causalontology/spec/schema/retraction.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/retraction.schema.json",
+  "title": "Retraction",
+  "type": "object",
+  "required": [
+    "id",
+    "retracts",
+    "source",
+    "timestamp"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^retraction:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "retraction"
+    },
+    "retracts": {
+      "type": "string",
+      "pattern": "^(assertion|enrichment):[0-9a-f]{64}$",
+      "description": "the assertion or enrichment being withdrawn"
+    },
+    "source": {
+      "type": "string",
+      "pattern": "^ed25519:[0-9a-f]{64}$",
+      "description": "must be the retracted record's source, or a key in its succession lineage"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{128}$"
+    }
+  }
+}

data/lib/causalontology/spec/schema/state.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://causalontology.org/schema/state.schema.json",
+  "title": "State Assertion",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "subject",
+    "quality",
+    "value",
+    "interval"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^state_assertion:[0-9a-f]{64}$"
+    },
+    "type": {
+      "const": "state_assertion"
+    },
+    "subject": {
+      "type": "string",
+      "pattern": "^token_individual:[0-9a-f]{64}$",
+      "description": "the PARTICULAR individual in this state"
+    },
+    "quality": {
+      "type": "string",
+      "pattern": "^quality:[0-9a-f]{64}$"
+    },
+    "value": {
+      "$ref": "#/$defs/value"
+    },
+    "interval": {
+      "$ref": "https://causalontology.org/schema/token.schema.json#/$defs/interval",
+      "description": "over what span of absolute time the subject held this value"
+    }
+  },
+  "$defs": {
+    "value": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "quantity",
+            "unit"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "quantity": {
+              "type": "number"
+            },
+            "unit": {
+              "type": "string",
+              "minLength": 1,
+              "description": "UCUM unit code; MUST match the quality's unit"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "categorical"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "categorical": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "boolean"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "boolean": {
+              "type": "boolean"
+            }
+          }
+        }
+      ]
+    }
+  }
+}