colregs 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colregs",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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/images.schema.json

@@ -14,7 +14,7 @@
       "additionalProperties": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["file", "bytes", "sha256", "pixels", "source_url", "source", "retrieved", "rights"],
+        "required": ["file", "bytes", "sha256", "pixels", "source_url", "source", "retrieved", "rights", "transcript", "subjects", "description", "shapes"],
         "properties": {
           "file": { "type": "string", "minLength": 1 },
           "bytes": { "type": "integer", "minimum": 0 },
@@ -44,6 +44,31 @@
             "minItems": 1,
             "items": { "type": "string", "minLength": 1 }
           },
+          "depicts": {
+            "description": "Whether the figure shows the provision of the clauses it is mapped to, the exception they carve out, or both.",
+            "enum": ["provision", "exception", "mixed"]
+          },
+          "transcript": {
+            "description": "Every printed text block in the image, verbatim, in reading order. Empty when the image carries no text.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "subjects": {
+            "description": "What is drawn, one noun phrase per vessel or object, in plain maritime vocabulary, not the Convention's classes.",
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "description": {
+            "description": "One paragraph of what the drawing contains: vessel type and its evidence, viewpoint, then the lights and shapes as drawn. No rule citations.",
+            "type": "string",
+            "minLength": 40
+          },
+          "shapes": {
+            "description": "The day shapes the figure draws, top to bottom, from the closed vocabulary. Empty when it draws none.",
+            "type": "array",
+            "items": { "enum": ["ball", "diamond", "cone-up", "cone-down", "cylinder", "basket", "flag-a"] }
+          },
           "provenance_status": { "type": "string" },
           "unmapped_reason": { "type": "string", "minLength": 1 }
         }

package/schema/rules.schema.json

@@ -2,10 +2,37 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mark-brannan/colregs/schema/rules.schema.json",
   "title": "data/rules.json",
-  "description": "Verbatim rule text keyed by paragraph path. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md.",
+  "description": "Rule text keyed by paragraph path, verbatim unless withheld under a licence bar. Structure only -- see docs/adr/0006-json-schema-and-identifier-diff.md and docs/adr/0010-text-withheld-jurisdictions.md.",
   "type": "object",
   "additionalProperties": false,
   "required": ["source", "paragraphs"],
+  "allOf": [
+    {
+      "$comment": "colregs#85: a withheld paragraph is a citation, not a reproduction (ADR 0010) -- 'retrieved' is when that citation was last checked against the primary source, so it can't be blank on a document that withholds text.",
+      "if": {
+        "properties": {
+          "paragraphs": {
+            "not": {
+              "type": "object",
+              "patternProperties": {
+                "^.*$": {
+                  "not": {
+                    "type": "object",
+                    "properties": { "text_status": { "const": "withheld" } },
+                    "required": ["text_status"]
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": { "retrieved": { "type": "string" } },
+        "required": ["retrieved"]
+      }
+    }
+  ],
   "properties": {
     "source": { "type": "string", "minLength": 1 },
     "source_url": { "type": "string", "minLength": 1 },
@@ -30,13 +57,59 @@
         "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["path", "rule", "rule_title", "jurisdiction", "text"],
+          "required": ["path", "rule", "rule_title", "jurisdiction"],
+          "allOf": [
+            {
+              "$comment": "ADR 0010: a withheld paragraph is modelled but ships no text.",
+              "if": {
+                "properties": { "text_status": { "const": "withheld" } },
+                "required": ["text_status"]
+              },
+              "then": {
+                "properties": {
+                  "text": false,
+                  "withheld_reason": { "type": "string", "minLength": 1 }
+                },
+                "required": ["withheld_reason"]
+              },
+              "else": {
+                "$comment": "mirrors, text_digest and text_slug are open to verbatim paragraphs too; only withheld_reason is incoherent without a bar.",
+                "properties": {
+                  "text": { "type": "string", "minLength": 1 },
+                  "withheld_reason": false
+                },
+                "required": ["text"]
+              }
+            }
+          ],
           "properties": {
             "path": { "type": "string", "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$" },
             "rule": { "type": "string", "pattern": "^[0-9]+$" },
             "rule_title": { "type": "string", "minLength": 1 },
             "jurisdiction": { "type": "string", "pattern": "^[a-z]+(/[a-z]+)*$" },
             "text": { "type": "string", "minLength": 1 },
+            "text_status": {
+              "$comment": "Absent means verbatim. 'withheld' means the text is not ours to publish -- ADR 0010.",
+              "enum": ["verbatim", "withheld"]
+            },
+            "withheld_reason": { "type": "string", "minLength": 1 },
+            "text_slug": {
+              "$comment": "Pencil, ADR 0010: sorted set of lemmatised key nouns and verbs, English counterparts where the source is not English. Defined so the option is not walled off; nothing writes it yet.",
+              "type": "array",
+              "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "text_digest": {
+              "$comment": "Pencil, ADR 0010: algorithm-qualified digest of the normalised text, e.g. 'sha256:<hex>'. Defined so the option is not walled off by additionalProperties; nothing writes it yet.",
+              "type": "string",
+              "pattern": "^[a-z0-9-]+:[A-Za-z0-9+/=]+$"
+            },
+            "mirrors": {
+              "$comment": "Paragraph path in intl this provision restates; display labelled as the international equivalent, never as this jurisdiction's text.",
+              "type": "string",
+              "pattern": "^[0-9]+(\\([a-z]\\))?(\\([ivx]+\\))?$"
+            },
             "images": {
               "type": "array",
               "items": { "type": "string", "minLength": 1 },