colregs 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colregs",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "COLREGS 72 and its national amalgamations as language-neutral JSON — rule text, light definitions, and applicability predicates — with cross-implementation fixtures",
   "license": "Apache-2.0",
   "repository": {

package/schema/applicability-fixtures.schema.json

@@ -8,14 +8,7 @@
   "additionalProperties": false,
   "required": ["jurisdiction", "cases"],
   "$defs": {
-    "factValue": {
-      "oneOf": [
-        { "type": "string", "pattern": "^[a-z][a-z0-9_]*:[a-z0-9_]+$" },
-        { "type": "number" },
-        { "type": "boolean" }
-      ]
-    },
-    "entryId": { "type": "string", "pattern": "^[0-9]+[a-z0-9]*(-[a-z0-9]+)?$" }
+    "ruleId": { "$ref": "applicability.schema.json#/$defs/ruleId" }
   },
   "properties": {
     "note": { "type": "string" },
@@ -31,16 +24,14 @@
           "name": { "type": "string", "minLength": 1 },
           "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
           "facts": {
+            "$comment": "A FactRecord (schema/fact-record.schema.json, ADR 0014); a case asserts at least one fact.",
             "type": "object",
             "minProperties": 1,
-            "additionalProperties": false,
-            "patternProperties": {
-              "^fact:[a-z0-9_]+$": { "$ref": "#/$defs/factValue" }
-            }
+            "$ref": "fact-record.schema.json"
           },
           "expect": {
             "type": "array",
-            "items": { "$ref": "#/$defs/entryId" }
+            "items": { "$ref": "#/$defs/ruleId" }
           }
         }
       }

package/schema/applicability.schema.json

@@ -7,10 +7,24 @@
   "additionalProperties": false,
   "required": ["entries"],
   "$defs": {
-    "entryId": { "type": "string", "pattern": "^[0-9]+[a-z0-9]*(-[a-z0-9]+)*$" },
+    "ruleCategory": {
+      "type": "string",
+      "enum": [
+        "category:definition",
+        "category:standard",
+        "category:scope",
+        "category:display",
+        "category:classification",
+        "category:precedence",
+        "category:conduct",
+        "category:care",
+        "category:meta"
+      ]
+    },
+    "ruleId": { "type": "string", "pattern": "^rule:[0-9]+[a-z]?(_[ivx]+)*(:[a-z][a-z0-9_]*)?$" },
     "modality": {
       "type": "string",
-      "enum": ["shall", "may", "shall-if-practicable", "conditional", "exempt", "shall-not", "shall-not-impede"]
+      "enum": ["modality:shall", "modality:may", "modality:shall-if-practicable", "modality:conditional", "modality:exempt", "modality:shall-not", "modality:shall-not-impede"]
     },
     "predicateValue": {
       "oneOf": [
@@ -81,13 +95,13 @@
       },
       "patternProperties": {
         "^fact:[a-z0-9_]+$": { "$ref": "#/$defs/predicateValue" },
-        "^(own|other):(fact|kin|geo|hist):[a-z0-9_]+$": { "$ref": "#/$defs/predicateValue" },
+        "^(self|other):(fact|kin|geo|hist):[a-z0-9_]+$": { "$ref": "#/$defs/predicateValue" },
         "^pair:(geo|env):[a-z0-9_]+$": { "$ref": "#/$defs/predicateValue" }
       }
     },
     "effectRole": {
       "type": "string",
-      "enum": ["give-way", "stand-on", "shall-not-impede", "keep-clear", "none"]
+      "enum": ["role:give-way", "role:stand-on", "role:shall-not-impede", "role:keep-clear", "role:none"]
     },
     "effect": {
       "oneOf": [
@@ -108,9 +122,9 @@
         {
           "type": "object",
           "additionalProperties": false,
-          "required": ["own", "other"],
+          "required": ["self", "other"],
           "properties": {
-            "own": { "$ref": "#/$defs/effectRole" },
+            "self": { "$ref": "#/$defs/effectRole" },
             "other": { "$ref": "#/$defs/effectRole" }
           }
         },
@@ -121,7 +135,7 @@
           "properties": {
             "encounter": {
               "type": "string",
-              "enum": ["head-on", "crossing", "overtaking", "none"]
+              "enum": ["encounter:head-on", "encounter:crossing", "encounter:overtaking", "encounter:none"]
             }
           }
         },
@@ -174,20 +188,20 @@
         "one_of": {
           "type": "array",
           "minItems": 2,
-          "items": { "$ref": "#/$defs/entryId" }
+          "items": { "$ref": "#/$defs/ruleId" }
         },
         "rel:includes": {
           "type": "array",
           "minItems": 1,
-          "items": { "$ref": "#/$defs/entryId" }
+          "items": { "$ref": "#/$defs/ruleId" }
         },
         "cite": { "type": "string", "minLength": 1 }
       }
     },
-    "entryIdList": {
+    "ruleIdList": {
       "type": "array",
       "minItems": 1,
-      "items": { "$ref": "#/$defs/entryId" }
+      "items": { "$ref": "#/$defs/ruleId" }
     }
   },
   "properties": {
@@ -216,48 +230,48 @@
       "type": "object",
       "additionalProperties": false,
       "required": [
-        "shall",
-        "may",
-        "shall-if-practicable",
-        "conditional",
-        "exempt",
-        "shall-not",
-        "shall-not-impede"
+        "modality:shall",
+        "modality:may",
+        "modality:shall-if-practicable",
+        "modality:conditional",
+        "modality:exempt",
+        "modality:shall-not",
+        "modality:shall-not-impede"
       ],
       "properties": {
-        "shall": { "type": "string" },
-        "may": { "type": "string" },
-        "shall-if-practicable": { "type": "string" },
-        "conditional": { "type": "string" },
-        "exempt": { "type": "string" },
-        "shall-not": { "type": "string" },
-        "shall-not-impede": { "type": "string" }
+        "modality:shall": { "type": "string" },
+        "modality:may": { "type": "string" },
+        "modality:shall-if-practicable": { "type": "string" },
+        "modality:conditional": { "type": "string" },
+        "modality:exempt": { "type": "string" },
+        "modality:shall-not": { "type": "string" },
+        "modality:shall-not-impede": { "type": "string" }
       }
     },
     "categories": {
       "type": "object",
       "additionalProperties": false,
       "required": [
-        "definition",
-        "standard",
-        "scope",
-        "display",
-        "classification",
-        "precedence",
-        "conduct",
-        "care",
-        "meta"
+        "category:definition",
+        "category:standard",
+        "category:scope",
+        "category:display",
+        "category:classification",
+        "category:precedence",
+        "category:conduct",
+        "category:care",
+        "category:meta"
       ],
       "properties": {
-        "definition": { "type": "string" },
-        "standard": { "type": "string" },
-        "scope": { "type": "string" },
-        "display": { "type": "string" },
-        "classification": { "type": "string" },
-        "precedence": { "type": "string" },
-        "conduct": { "type": "string" },
-        "care": { "type": "string" },
-        "meta": { "type": "string" }
+        "category:definition": { "type": "string" },
+        "category:standard": { "type": "string" },
+        "category:scope": { "type": "string" },
+        "category:display": { "type": "string" },
+        "category:classification": { "type": "string" },
+        "category:precedence": { "type": "string" },
+        "category:conduct": { "type": "string" },
+        "category:care": { "type": "string" },
+        "category:meta": { "type": "string" }
       }
     },
     "effects": {
@@ -269,24 +283,24 @@
         "roles": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["give-way", "stand-on", "shall-not-impede", "keep-clear", "none"],
+          "required": ["role:give-way", "role:stand-on", "role:shall-not-impede", "role:keep-clear", "role:none"],
           "properties": {
-            "give-way": { "type": "string" },
-            "stand-on": { "type": "string" },
-            "shall-not-impede": { "type": "string" },
-            "keep-clear": { "type": "string" },
-            "none": { "type": "string" }
+            "role:give-way": { "type": "string" },
+            "role:stand-on": { "type": "string" },
+            "role:shall-not-impede": { "type": "string" },
+            "role:keep-clear": { "type": "string" },
+            "role:none": { "type": "string" }
           }
         },
         "encounters": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["head-on", "crossing", "overtaking", "none"],
+          "required": ["encounter:head-on", "encounter:crossing", "encounter:overtaking", "encounter:none"],
           "properties": {
-            "head-on": { "type": "string" },
-            "crossing": { "type": "string" },
-            "overtaking": { "type": "string" },
-            "none": { "type": "string" }
+            "encounter:head-on": { "type": "string" },
+            "encounter:crossing": { "type": "string" },
+            "encounter:overtaking": { "type": "string" },
+            "encounter:none": { "type": "string" }
           }
         },
         "classification_shape": { "type": "string" }
@@ -312,27 +326,14 @@
         "additionalProperties": false,
         "required": ["id", "jurisdiction", "cite", "category", "note"],
         "properties": {
-          "id": { "$ref": "#/$defs/entryId" },
+          "id": { "$ref": "#/$defs/ruleId" },
           "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
           "cite": { "type": "string", "minLength": 1 },
-          "category": { "type": "string", "enum": ["care", "meta"] },
+          "category": { "type": "string", "enum": ["category:care", "category:meta"] },
           "note": { "type": "string", "minLength": 1 }
         }
       }
     },
-    "retired_entry_ids": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ids"],
-      "properties": {
-        "note": { "type": "string" },
-        "ids": {
-          "type": "object",
-          "propertyNames": { "$ref": "#/$defs/entryId" },
-          "additionalProperties": { "type": "string", "minLength": 1 }
-        }
-      }
-    },
     "entries": {
       "type": "array",
       "minItems": 1,
@@ -341,12 +342,11 @@
         "additionalProperties": false,
         "required": ["id", "jurisdiction", "cite", "when", "modality"],
         "properties": {
-          "id": { "$ref": "#/$defs/entryId" },
+          "id": { "$ref": "#/$defs/ruleId" },
           "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
           "cite": { "type": "string", "minLength": 1 },
           "category": {
-            "type": "string",
-            "enum": ["definition", "standard", "scope", "display", "classification", "precedence", "conduct", "care", "meta"]
+            "$ref": "#/$defs/ruleCategory"
           },
           "subjects": { "type": "integer", "const": 2 },
           "when": { "$ref": "#/$defs/situationWhen" },
@@ -366,16 +366,16 @@
           "note": { "type": "string" },
           "gap": { "type": "string", "minLength": 1 },
           "no_gate_note": { "type": "string", "minLength": 1 },
-          "rel:includes": { "$ref": "#/$defs/entryIdList" },
+          "rel:includes": { "$ref": "#/$defs/ruleIdList" },
           "rel:conditional_includes": {
             "type": "array",
             "minItems": 1,
             "items": { "$ref": "#/$defs/conditionalInclude" }
           },
-          "rel:in_lieu_of": { "$ref": "#/$defs/entryIdList" },
-          "rel:excludes": { "$ref": "#/$defs/entryIdList" },
-          "rel:exempts": { "$ref": "#/$defs/entryIdList" },
-          "rel:overrides": { "$ref": "#/$defs/entryIdList" }
+          "rel:in_lieu_of": { "$ref": "#/$defs/ruleIdList" },
+          "rel:excludes": { "$ref": "#/$defs/ruleIdList" },
+          "rel:exempts": { "$ref": "#/$defs/ruleIdList" },
+          "rel:overrides": { "$ref": "#/$defs/ruleIdList" }
         },
         "allOf": [
           {

package/schema/conduct-evaluation.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/conduct-evaluation.schema.json",
+  "title": "ConductEvaluation",
+  "description": "The result of evaluateConduct: one verdict per applied conduct entry per subject over the window the caller handed over, and the Rule 13(d)/17 phase changes seen (ADR 0012 §3, ADR 0014). Structure only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "colregs",
+    "window",
+    "applied",
+    "verdicts",
+    "phases"
+  ],
+  "properties": {
+    "colregs": {
+      "$ref": "evaluation.schema.json#/$defs/colregs"
+    },
+    "window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "from_s",
+        "to_s",
+        "samples"
+      ],
+      "properties": {
+        "from_s": {
+          "type": "number"
+        },
+        "to_s": {
+          "type": "number"
+        },
+        "samples": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "applied": {
+      "$ref": "evaluation.schema.json#/$defs/ruleIds"
+    },
+    "verdicts": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/verdict"
+      }
+    },
+    "phases": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/phaseChange"
+      }
+    }
+  },
+  "$defs": {
+    "subject": {
+      "type": "string",
+      "enum": [
+        "self",
+        "other"
+      ]
+    },
+    "verdict": {
+      "$comment": "`pending`: the window ended before the duty could be judged. An entry that never attached is absent, not pending.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "subject",
+        "verdict"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "evaluation.schema.json#/$defs/ruleId"
+        },
+        "subject": {
+          "$ref": "#/$defs/subject"
+        },
+        "verdict": {
+          "type": "string",
+          "enum": [
+            "kept",
+            "breached",
+            "pending"
+          ]
+        },
+        "attached_at_s": {
+          "type": "number"
+        },
+        "decided_at_s": {
+          "type": "number"
+        },
+        "robustness": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "value",
+            "unit"
+          ],
+          "properties": {
+            "value": {
+              "type": "number"
+            },
+            "unit": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
+    "phaseChange": {
+      "$comment": "`phase` is a paragraph cite, never an entry id: several phases have no entry.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "subject",
+        "phase",
+        "at_s"
+      ],
+      "properties": {
+        "subject": {
+          "$ref": "#/$defs/subject"
+        },
+        "phase": {
+          "$ref": "evaluation.schema.json#/$defs/paragraphCite"
+        },
+        "at_s": {
+          "type": "number"
+        }
+      }
+    }
+  }
+}

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