colregs 0.2.4 → 0.3.1

package/schema/display-evaluation.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/display-evaluation.schema.json",
+  "title": "DisplayEvaluation",
+  "description": "The result of evaluateDisplay: every complete lawful display for one vessel, alternatives unresolved (REQ-MODEL-8), with the data it was read against (ADR 0011 §1, ADR 0014). Structure only; the $defs shared with the other envelopes live in schema/evaluation.schema.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "colregs",
+    "applied",
+    "exempted",
+    "excluded",
+    "overridden",
+    "displays",
+    "optional_additions",
+    "modalities",
+    "categories",
+    "provenance"
+  ],
+  "properties": {
+    "colregs": {
+      "$ref": "evaluation.schema.json#/$defs/colregs"
+    },
+    "applied": {
+      "$ref": "evaluation.schema.json#/$defs/ruleIds"
+    },
+    "exempted": {
+      "$ref": "evaluation.schema.json#/$defs/byEntryList"
+    },
+    "excluded": {
+      "$ref": "evaluation.schema.json#/$defs/byEntryList"
+    },
+    "overridden": {
+      "$ref": "evaluation.schema.json#/$defs/byEntryList"
+    },
+    "displays": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/display"
+      }
+    },
+    "optional_additions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "lights",
+          "cite"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "evaluation.schema.json#/$defs/ruleId"
+          },
+          "via": {
+            "$ref": "evaluation.schema.json#/$defs/ruleId"
+          },
+          "lights": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/displayLight"
+            }
+          },
+          "cite": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "optionalAdditions": {
+      "deprecated": true,
+      "$comment": "Renamed to optional_additions (ADR 0011 §4); an implementation may still emit both.",
+      "type": "array",
+      "items": {
+        "$ref": "#/properties/optional_additions/items"
+      }
+    },
+    "modalities": {
+      "$ref": "evaluation.schema.json#/$defs/modalities"
+    },
+    "categories": {
+      "$ref": "evaluation.schema.json#/$defs/categories"
+    },
+    "provenance": {
+      "$ref": "evaluation.schema.json#/$defs/provenance"
+    }
+  },
+  "$defs": {
+    "displayLight": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "spec",
+        "source_entry",
+        "modality"
+      ],
+      "properties": {
+        "spec": {
+          "$ref": "applicability.schema.json#/$defs/lightRef"
+        },
+        "source_entry": {
+          "$ref": "evaluation.schema.json#/$defs/ruleId"
+        },
+        "sourceEntry": {
+          "deprecated": true,
+          "$comment": "Renamed to source_entry (ADR 0011 §4).",
+          "$ref": "evaluation.schema.json#/$defs/ruleId"
+        },
+        "via": {
+          "$ref": "evaluation.schema.json#/$defs/ruleId"
+        },
+        "modality": {
+          "$ref": "applicability.schema.json#/$defs/modality"
+        }
+      }
+    },
+    "display": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "entries",
+        "lights",
+        "chosen"
+      ],
+      "properties": {
+        "entries": {
+          "$ref": "evaluation.schema.json#/$defs/ruleIds"
+        },
+        "lights": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/displayLight"
+          }
+        },
+        "chosen": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/editions.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/editions.schema.json",
+  "title": "data/editions.json",
+  "description": "Registry of instruments and their editions, per jurisdiction: the layer GATE-2 asked for. The skeleton names the edition it consolidates; every corpus names the edition its text reflects; two editions of one jurisdiction may be registered at once. See docs/adr/0013-corpus-files-with-editions.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["jurisdictions"],
+  "properties": {
+    "note": { "type": "string" },
+    "jurisdictions": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z]+(/[a-z]+)*$": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["instrument", "skeleton", "editions"],
+          "properties": {
+            "instrument": { "$comment": "The body of rules this jurisdiction's editions are editions of.", "type": "string", "minLength": 1 },
+            "skeleton": {
+              "$comment": "Which edition data/rules.json consolidates for this jurisdiction; null while the skeleton has no paragraphs of it.",
+              "oneOf": [{ "type": "null" }, { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*@[a-z0-9-]+$" }]
+            },
+            "editions": {
+              "type": "object",
+              "additionalProperties": false,
+              "patternProperties": {
+                "^[a-z]+(/[a-z]+)*@[a-z0-9-]+$": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["amended_through", "in_force"],
+                  "properties": {
+                    "amended_through": { "$comment": "Free text: national amalgamations cite their own amending acts, not IMO resolutions.", "type": "string", "minLength": 1 },
+                    "in_force": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+                    "superseded_by": { "$comment": "The later edition, where two are registered and one has lapsed.", "type": "string", "pattern": "^[a-z]+(/[a-z]+)*@[a-z0-9-]+$" },
+                    "note": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/encounter-evaluation.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/encounter-evaluation.schema.json",
+  "title": "EncounterEvaluation",
+  "description": "The result of evaluateEncounter: two vessels at one instant -- scope, encounter class, risk of collision with its grounds, roles as a set per subject, overrides and modalities (ADR 0011 §4, ADR 0014). Structure only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "colregs",
+    "applied",
+    "scope",
+    "risk_of_collision",
+    "roles",
+    "overridden",
+    "modalities",
+    "categories",
+    "provenance"
+  ],
+  "properties": {
+    "colregs": {
+      "$ref": "evaluation.schema.json#/$defs/colregs"
+    },
+    "applied": {
+      "$ref": "evaluation.schema.json#/$defs/ruleIds"
+    },
+    "scope": {
+      "$ref": "evaluation.schema.json#/$defs/ruleIds"
+    },
+    "encounter": {
+      "$comment": "Absent when no classification entry fired: cannot say, not none (Q-43).",
+      "type": "string",
+      "enum": [
+        "head-on",
+        "crossing",
+        "overtaking",
+        "none"
+      ]
+    },
+    "risk_of_collision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "asserted",
+        "by"
+      ],
+      "properties": {
+        "asserted": {
+          "type": "boolean"
+        },
+        "by": {
+          "$ref": "evaluation.schema.json#/$defs/ruleIds"
+        }
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "own",
+        "other"
+      ],
+      "properties": {
+        "own": {
+          "$ref": "#/$defs/subjectRoles"
+        },
+        "other": {
+          "$ref": "#/$defs/subjectRoles"
+        }
+      }
+    },
+    "overridden": {
+      "$ref": "evaluation.schema.json#/$defs/byEntryList"
+    },
+    "modalities": {
+      "$ref": "evaluation.schema.json#/$defs/modalities"
+    },
+    "categories": {
+      "$ref": "evaluation.schema.json#/$defs/categories"
+    },
+    "provenance": {
+      "$ref": "evaluation.schema.json#/$defs/provenance"
+    }
+  },
+  "$defs": {
+    "subjectRole": {
+      "$comment": "Roles are a set per subject, each citing the entry that assigned it (Q-36).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "role",
+        "by"
+      ],
+      "properties": {
+        "role": {
+          "$ref": "applicability.schema.json#/$defs/effectRole"
+        },
+        "by": {
+          "$ref": "evaluation.schema.json#/$defs/ruleId"
+        }
+      }
+    },
+    "subjectRoles": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/subjectRole"
+      }
+    }
+  }
+}

package/schema/evaluation.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/evaluation.schema.json",
+  "title": "Evaluation",
+  "description": "The $defs every result envelope shares (ADR 0014): the colregs provenance stamp, what an evaluation read, entry-id and paragraph-cite vocabularies. No instance validates against the root; the envelopes under schema/*-evaluation.schema.json and the operations manifest $ref into $defs here.",
+  "$defs": {
+    "ruleId": {
+      "$ref": "applicability.schema.json#/$defs/ruleId"
+    },
+    "ruleIds": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ruleId"
+      }
+    },
+    "paragraphCite": {
+      "$comment": "A Rules paragraph path, the vocabulary of `phase` and `breaches` (ADR 0011 §4); the pattern is data/rules.json's paragraph key, and the tests hold the two equal.",
+      "type": "string",
+      "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$"
+    },
+    "colregs": {
+      "$comment": "`resolved`: the data is the implementation's own colregs dependency and `version` describes it exactly. `caller`: the caller supplied the data and `version` names only the release the implementation resolved.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "source"
+      ],
+      "properties": {
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "enum": [
+            "resolved",
+            "caller"
+          ]
+        }
+      }
+    },
+    "byEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "by"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/ruleId"
+        },
+        "by": {
+          "$ref": "#/$defs/ruleId"
+        }
+      }
+    },
+    "byEntryList": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/byEntry"
+      }
+    },
+    "modalities": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^rule:[0-9]+[a-z]?(_[ivx]+)*(:[a-z][a-z0-9_]*)?$": {
+          "$ref": "applicability.schema.json#/$defs/modality"
+        }
+      }
+    },
+    "categories": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^rule:[0-9]+[a-z]?(_[ivx]+)*(:[a-z][a-z0-9_]*)?$": {
+          "$ref": "#/$defs/ruleCategory"
+        }
+      }
+    },
+    "ruleCategory": {
+      "$ref": "applicability.schema.json#/$defs/ruleCategory"
+    },
+    "representedParagraph": {
+      "$comment": "One of data/applicability.json's represented_paragraphs without its note: an evaluation carries the identity, not the prose.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "jurisdiction",
+        "cite",
+        "category"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "applicability.schema.json#/$defs/ruleId"
+        },
+        "jurisdiction": {
+          "type": "string",
+          "pattern": "^[a-z]+(/[a-z]+)*$"
+        },
+        "cite": {
+          "type": "string",
+          "minLength": 1
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "care",
+            "meta"
+          ]
+        }
+      }
+    },
+    "provenance": {
+      "$comment": "What an evaluation read, and therefore what its answer does not cover: the categories it matched, the jurisdictions offered, and the paragraphs no verb computes.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "evaluated_categories",
+        "jurisdictions",
+        "represented"
+      ],
+      "properties": {
+        "evaluated_categories": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ruleCategory"
+          }
+        },
+        "jurisdictions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]+(/[a-z]+)*$"
+          }
+        },
+        "represented": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/representedParagraph"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/fact-record.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/fact-record.schema.json",
+  "title": "FactRecord",
+  "description": "What a consumer asserts about one vessel at one moment: the input evaluateDisplay reads (ADR 0011 §2, ADR 0014). Structure only -- which fact keys exist and which values each takes is data/facts.json's, checked in the tests; see docs/adr/0006-json-schema-and-identifier-diff.md.",
+  "$comment": "A case's `facts` in schema/applicability-fixtures.schema.json is this shape plus minProperties: 1 -- a fixture must assert something; an evaluation input need not, and `{}` is a record that asserts nothing. Values are string, number or boolean, as data/facts.json declares them; null and positions belong to the situation classes.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^fact:[a-z0-9_]+$": {
+      "$ref": "#/$defs/factValue"
+    }
+  },
+  "$defs": {
+    "factValue": {
+      "oneOf": [
+        {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*:[a-z0-9_]+$"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        }
+      ]
+    }
+  }
+}

package/schema/i18n-catalog.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/i18n-catalog.schema.json",
+  "title": "data/i18n/*.json",
+  "description": "Display catalog for one BCP 47 language: UI strings for identifier vocabularies (light names, fact-axis labels, modality labels, image captions), not legal text -- see docs/adr/0003-language-as-a-dimension.md 'Display catalogs'.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["language", "provenance", "strings"],
+  "properties": {
+    "language": {
+      "type": "string",
+      "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]+)*$",
+      "description": "BCP 47 tag, e.g. en, fi. Must equal the filename stem; test/data.test.mjs checks."
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contributors", "reviewed_by", "review_date"],
+      "properties": {
+        "contributors": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "reviewed_by": { "type": "array", "items": { "type": "string" }, "description": "Named human reviewers. Empty means unreviewed: the strings are on file but not yet vouched for." },
+        "review_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+        "licence": { "type": "string", "description": "Optional until the data licence question (Q-9) is ruled; absent means the package licence applies." }
+      }
+    },
+    "strings": {
+      "type": "object",
+      "description": "One section per vocabulary. Identifier vocabularies (light) are keyed by the identifier itself, as documented in docs/identifiers.md; closed vocabularies (modality) by their bare value, as stored in data/applicability.json. Values are static strings: no interpolation, no plurals -- the consumer's i18n system owns composition.",
+      "additionalProperties": false,
+      "properties": {
+        "light": {
+          "type": "object",
+          "propertyNames": { "pattern": "^light:[a-z_]+$" },
+          "additionalProperties": { "$ref": "#/$defs/label" }
+        },
+        "modality": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z]+(-[a-z]+)*$" },
+          "additionalProperties": { "$ref": "#/$defs/label" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "label": { "type": "string", "minLength": 1 }
+  }
+}

package/schema/operations.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/operations.schema.json",
+  "title": "data/operations.json",
+  "description": "The engine interface colregs owns (ADR 0014): one operation per verb ADR 0011 and ADR 0012 name, each binding its positional inputs and its result to a schema under schema/, its entry-id companion, and the fixture cases that exercise it. Structure only -- that every schema reference resolves and every fixture file is bound is checked in the tests.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "operations"
+  ],
+  "$defs": {
+    "verb": {
+      "type": "string",
+      "pattern": "^[a-z][A-Za-z0-9]*$"
+    },
+    "schemaRef": {
+      "$comment": "A file under schema/, optionally with a JSON pointer into it; relative to the package root.",
+      "type": "string",
+      "pattern": "^schema/[a-z0-9-]+\\.schema\\.json(#/[^#]+)?$"
+    },
+    "adr": {
+      "type": "string",
+      "pattern": "^[0-9]{4}$"
+    }
+  },
+  "properties": {
+    "note": {
+      "type": "string"
+    },
+    "operations": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "patternProperties": {
+        "^[a-z][A-Za-z0-9]*$": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "adr",
+            "inputs",
+            "output",
+            "fixtures"
+          ],
+          "properties": {
+            "adr": {
+              "$ref": "#/$defs/adr"
+            },
+            "inputs": {
+              "$comment": "Positional, in call order. Anything a binding accepts after them (an options bag, a data override) is the binding's own and is not named here.",
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "name",
+                  "schema"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9_]*$"
+                  },
+                  "schema": {
+                    "$ref": "#/$defs/schemaRef"
+                  }
+                }
+              }
+            },
+            "output": {
+              "$ref": "#/$defs/schemaRef"
+            },
+            "companion": {
+              "$comment": "The verb that takes the same inputs and answers only the applied entry ids -- the fixture contract, since every fixture case `expect`s entry ids.",
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "verb",
+                "output"
+              ],
+              "properties": {
+                "verb": {
+                  "$ref": "#/$defs/verb"
+                },
+                "output": {
+                  "$ref": "#/$defs/schemaRef"
+                }
+              }
+            },
+            "fixtures": {
+              "$comment": "Each binds a fixture file whose `cases[]` carry this operation's inputs, in order, under the `case_inputs` keys, and the expected answer under `expect` -- the companion's entry ids unless `expect` names another schema. A case's `status` and `jurisdiction` are the fixture file's own and are read there. Empty until a fixture file for the input exists.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "file",
+                  "case_inputs"
+                ],
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "pattern": "^fixtures/[a-z0-9-]+\\.json$"
+                  },
+                  "case_inputs": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "pattern": "^[a-z][a-z0-9_]*$"
+                    }
+                  },
+                  "expect": {
+                    "$ref": "#/$defs/schemaRef"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}