colregs 0.3.0 → 0.3.1

package/schema/situation-fixtures.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mark-brannan/colregs/schema/situation-fixtures.schema.json",
   "title": "fixtures/situation-fixtures.json",
-  "description": "Two-subject situation fixtures (ADR 0005, REQ-CAT-5). Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md. Namespace resolution (every kin:/geo:/hist: key declared in facts.json) stays in the tests.",
+  "description": "Two-subject situation fixtures (ADR 0005, REQ-CAT-5). Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md. A case's situation is schema/situation.schema.json; namespace resolution (every kin:/geo:/hist: key declared in facts.json) stays in the tests.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -12,26 +12,16 @@
     "cases"
   ],
   "$defs": {
-    "entryId": {
-      "type": "string",
-      "pattern": "^[0-9]+[a-z0-9]*(-[a-z0-9]+)*$"
+    "ruleId": {
+      "$ref": "applicability.schema.json#/$defs/ruleId"
     },
     "modality": {
-      "type": "string",
-      "enum": [
-        "shall",
-        "may",
-        "shall-if-practicable",
-        "conditional",
-        "exempt",
-        "shall-not",
-        "shall-not-impede"
-      ]
+      "$ref": "applicability.schema.json#/$defs/modality"
     },
     "expectItem": {
       "oneOf": [
         {
-          "$ref": "#/$defs/entryId"
+          "$ref": "#/$defs/ruleId"
         },
         {
           "type": "object",
@@ -42,7 +32,7 @@
           ],
           "properties": {
             "entry": {
-              "$ref": "#/$defs/entryId"
+              "$ref": "#/$defs/ruleId"
             },
             "modality": {
               "$ref": "#/$defs/modality"
@@ -50,109 +40,6 @@
           }
         }
       ]
-    },
-    "scalar": {
-      "oneOf": [
-        {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9_]*:[a-z0-9_]+$"
-        },
-        {
-          "type": "number"
-        },
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "latitude",
-            "longitude"
-          ],
-          "properties": {
-            "latitude": {
-              "type": "number",
-              "minimum": -90,
-              "maximum": 90
-            },
-            "longitude": {
-              "type": "number",
-              "minimum": -180,
-              "maximum": 180
-            }
-          }
-        }
-      ]
-    },
-    "factRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^fact:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "kinRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^kin:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "geoRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^geo:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "histRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^hist:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "envRecord": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^env:[a-z0-9_]+$": {
-          "$ref": "#/$defs/scalar"
-        }
-      }
-    },
-    "vessel": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "fact"
-      ],
-      "properties": {
-        "fact": {
-          "$ref": "#/$defs/factRecord"
-        },
-        "kin": {
-          "$ref": "#/$defs/kinRecord"
-        },
-        "geo": {
-          "$ref": "#/$defs/geoRecord"
-        },
-        "hist": {
-          "$ref": "#/$defs/histRecord"
-        }
-      }
     }
   },
   "properties": {
@@ -200,7 +87,7 @@
           "type": "string"
         },
         "bare": {
-          "$ref": "#/$defs/entryId"
+          "$ref": "#/$defs/ruleId"
         },
         "with_modality": {
           "type": "object",
@@ -211,7 +98,7 @@
           ],
           "properties": {
             "entry": {
-              "$ref": "#/$defs/entryId"
+              "$ref": "#/$defs/ruleId"
             },
             "modality": {
               "$ref": "#/$defs/modality"
@@ -286,31 +173,8 @@
             }
           },
           "situation": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-              "own"
-            ],
-            "properties": {
-              "own": {
-                "$ref": "#/$defs/vessel"
-              },
-              "other": {
-                "$ref": "#/$defs/vessel"
-              },
-              "pair": {
-                "type": "object",
-                "additionalProperties": false,
-                "properties": {
-                  "geo": {
-                    "$ref": "#/$defs/geoRecord"
-                  },
-                  "env": {
-                    "$ref": "#/$defs/envRecord"
-                  }
-                }
-              }
-            }
+            "$comment": "A Situation (schema/situation.schema.json, ADR 0014).",
+            "$ref": "situation.schema.json"
           }
         }
       }

package/schema/situation.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/situation.schema.json",
+  "title": "Situation",
+  "description": "Two vessels and the encounter at one instant: the input evaluateEncounter reads, nested by subject and class (ADR 0005 §2, ADR 0011 §3, ADR 0014). Structure only -- every kin:/geo:/hist:/env: key must be declared in data/facts.json §situation, checked in the tests.",
+  "$comment": "The same shape as a case's `situation` in schema/situation-fixtures.schema.json, stated once here so an operation can name it; `own` required, `other` optional (Rule 19's single-vessel scope), every class and key optional -- absent is absent.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["own"],
+  "properties": {
+    "own": { "$ref": "#/$defs/subject" },
+    "other": { "$ref": "#/$defs/subject" },
+    "pair": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "geo": { "$ref": "#/$defs/geoRecord" },
+        "env": { "$ref": "#/$defs/envRecord" }
+      }
+    }
+  },
+  "$defs": {
+    "scalar": {
+      "oneOf": [
+        { "type": "string", "pattern": "^[a-z][a-z0-9_]*:[a-z0-9_]+$" },
+        { "type": "number" },
+        { "type": "boolean" },
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["latitude", "longitude"],
+          "properties": {
+            "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
+            "longitude": { "type": "number", "minimum": -180, "maximum": 180 }
+          }
+        }
+      ]
+    },
+    "kinRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^kin:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "geoRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^geo:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "histRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^hist:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "envRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": { "^env:[a-z0-9_]+$": { "$ref": "#/$defs/scalar" } }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fact"],
+      "properties": {
+        "fact": { "$ref": "fact-record.schema.json" },
+        "kin": { "$ref": "#/$defs/kinRecord" },
+        "geo": { "$ref": "#/$defs/geoRecord" },
+        "hist": { "$ref": "#/$defs/histRecord" }
+      }
+    }
+  }
+}

package/schema/trace.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mark-brannan/colregs/schema/trace.schema.json",
+  "title": "Trace",
+  "description": "The situation over time: the window evaluateConduct reads (ADR 0012 §2, ADR 0014). A conforming implementation rejects an empty samples list, a `t_s` that does not strictly increase, and `other` present in some samples and absent in others; `t_s` is seconds on the caller's clock, read as differences only, and the pair's identity is the caller's, since a Situation names no vessel. Structure only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "samples"
+  ],
+  "properties": {
+    "samples": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "t_s",
+          "situation"
+        ],
+        "properties": {
+          "t_s": {
+            "type": "number"
+          },
+          "situation": {
+            "$ref": "situation.schema.json"
+          }
+        }
+      }
+    }
+  }
+}

package/data/deprecated-identifiers.json

@@ -1,7 +0,0 @@
-{
- "entry:14a": {
-  "denoted": "The head-on classification: encounter head-on when each vessel has the other ahead or nearly ahead, cited to 14(a). Renamed when the cite moved to 14(b), the deeming paragraph the entry actually reads (Q-45); the predicate and effect are unchanged.",
-  "deprecated_in": "0.2.0",
-  "replacement": "entry:14b"
- }
-}

package/schema/deprecated-identifiers.schema.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/mark-brannan/colregs/schema/deprecated-identifiers.schema.json",
-  "title": "data/deprecated-identifiers.json",
-  "description": "REQ-MODEL-11's deprecation registry: every retired identifier, what it denoted, the version that deprecated it, and its replacement where one exists. Keys are the same prefixed forms the identifier diff compares (test/data.test.mjs's extractIdentifiers) -- e.g. 'entry:25d2', 'paragraph:27(a)(i)', 'light:masthead', 'fact-key:activity', 'fact-value:activity:nuc', 'rel:includes'. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md.",
-  "type": "object",
-  "additionalProperties": {
-    "type": "object",
-    "additionalProperties": false,
-    "required": ["denoted", "deprecated_in"],
-    "properties": {
-      "denoted": {
-        "type": "string",
-        "minLength": 1,
-        "description": "What the identifier meant, so a consumer pinned to an old version can resolve a stale reference without the identifier itself."
-      },
-      "deprecated_in": {
-        "type": "string",
-        "pattern": "^\\d+\\.\\d+\\.\\d+$",
-        "description": "The released version that deprecated this identifier (REQ-MODEL-10)."
-      },
-      "replacement": {
-        "type": ["string", "null"],
-        "minLength": 1,
-        "description": "The identifier that replaces this one, in the same prefixed form, or null where nothing replaces it."
-      }
-    }
-  }
-}