Add column semantics to the Wrangle Registry

registry/CONTRACT.md

@@ -200,6 +200,28 @@ Parameter records contain human guidance plus a JSON Schema fragment. Every
 runtime-owned parameter fact must reconcile with the pinned manifest and be
 traceable to the named runtime symbol.
 
+Parameters whose values directly identify dataframe columns may also declare
+optional `column_semantics`. Its `role` is `reference` when the value selects a
+column that must exist before the step and `destination` when the value names a
+column where the step writes results. Its `cardinality` is `scalar`, `list`, or
+`scalar_or_list`, matching the accepted JSON Schema shape; nullability remains
+part of the parameter's `schema` and does not change cardinality. The compiler
+copies this object into each per-wrangle contract and emits it as the
+`x-wrangles-column` annotation on the corresponding generated recipe-schema
+property.
+
+Column semantics are valid only when every non-null value shape exposes column
+identifiers directly: a scalar is a string or integer, and a list is an array
+whose `items` schema accepts only strings or integers. Unconstrained arrays,
+nested arrays, objects, mappings, and `$ref`/`allOf` shapes are not annotated.
+Those forms require a future locator vocabulary that can say where within the
+value the column identifier appears (for example, in a mapping key).
+
+This metadata describes column-name syntax, not dataframe state transitions. A
+destination may create, overwrite, or conditionally reuse a column. The current
+Registry has no validated effect vocabulary for add, rename, or remove, so
+consumers must not infer those effects from `role` or parameter names.
+
 Every parameter also declares one `param_group` from a small shared vocabulary:
 
 - `I/O` identifies input and output columns or structures.
@@ -309,9 +331,12 @@ terminated by one newline (`utf8-newline-separated-sorted-v1`).
 
 ## Versioning and lifecycle
 
-The pre-production Registry version is `0.2.0`. Version `0.2.0` makes the
+The pre-production Registry version is `0.2.1`. Version `0.2.0` makes the
 fail-closed Recipe Writer eligibility decision required for every entry and
 adds the compiled-contract and integrity metadata consumed by Registry clients.
+Version `0.2.1` introduces optional column-role and cardinality metadata plus
+explicit direct-item schemas for its representative list parameters, while
+retaining the `0.2` entry schema compatibility series.
 A production release will
 contain:
 

registry/reports/runtime-reconciliation.json

@@ -1,7 +1,7 @@
 {
   "format": "wrangles-registry-reconciliation",
   "format_version": "0.2",
-  "registry_version": "0.2.0",
+  "registry_version": "0.2.1",
   "runtime_source": {
     "repository": "https://github.com/wrangleworks/WranglesPY",
     "version": "1.20.2",
@@ -1089,6 +1089,9 @@
           "code": "schema_constraint_difference",
           "parameter": "columns",
           "registry_schema": {
+            "items": {
+              "type": "string"
+            },
             "type": [
               "string",
               "array"
@@ -3254,6 +3257,12 @@
           "code": "schema_constraint_difference",
           "parameter": "input",
           "registry_schema": {
+            "items": {
+              "type": [
+                "string",
+                "integer"
+              ]
+            },
             "type": [
               "string",
               "integer",
@@ -3273,6 +3282,9 @@
           "code": "schema_constraint_difference",
           "parameter": "output",
           "registry_schema": {
+            "items": {
+              "type": "string"
+            },
             "type": [
               "string",
               "array",
@@ -4261,6 +4273,30 @@
             "type": "boolean"
           }
         },
+        {
+          "code": "schema_constraint_difference",
+          "parameter": "input",
+          "registry_schema": {
+            "items": {
+              "type": [
+                "string",
+                "integer"
+              ]
+            },
+            "type": [
+              "string",
+              "integer",
+              "array"
+            ]
+          },
+          "docstring_schema": {
+            "type": [
+              "string",
+              "integer",
+              "array"
+            ]
+          }
+        },
         {
           "code": "schema_constraint_difference",
           "parameter": "normalization",
@@ -4293,6 +4329,12 @@
           "code": "schema_constraint_difference",
           "parameter": "output",
           "registry_schema": {
+            "items": {
+              "type": [
+                "string",
+                "integer"
+              ]
+            },
             "type": [
               "string",
               "integer",

registry/reports/runtime-reconciliation.md

@@ -4,7 +4,7 @@ Generated file. Do not edit directly.
 
 - Runtime version: `1.20.2`
 - Runtime source: [`7916bf158e8b7e561270a1bea7b808f88956edc4`](https://github.com/wrangleworks/WranglesPY/commit/7916bf158e8b7e561270a1bea7b808f88956edc4)
-- Registry version: `0.2.0`
+- Registry version: `0.2.1`
 - Runtime entries: 98
 - Embedded Python schema docstrings: 96
 - Existing quasi-registry records: 93
@@ -119,7 +119,7 @@ capabilities must reconcile; individual records can be curated in place later.
 | `split.tokenize` | `split.tokenize` | verified | 0 | 1 |
 | `sql` | `sql` | verified | 0 | 3 |
 | `standardize` | `standardize` | verified | 0 | 3 |
-| `standardize.clean` | `standardize.clean` | verified | 0 | 12 |
+| `standardize.clean` | `standardize.clean` | verified | 0 | 13 |
 | `standardize.custom` | `standardize.custom` | verified | 0 | 3 |
 | `translate` | `translate` | verified | 0 | 1 |
 | `transpose` | `transpose` | verified | 0 | 1 |
@@ -365,6 +365,7 @@ capabilities must reconcile; individual records can be curated in place later.
 | `standardize.clean` | schema_constraint_difference | `collapse_whitespace` | See the JSON report for both schema fragments. |
 | `standardize.clean` | schema_constraint_difference | `fix_character_width` | See the JSON report for both schema fragments. |
 | `standardize.clean` | schema_constraint_difference | `fix_encoding` | See the JSON report for both schema fragments. |
+| `standardize.clean` | schema_constraint_difference | `input` | See the JSON report for both schema fragments. |
 | `standardize.clean` | schema_constraint_difference | `normalization` | See the JSON report for both schema fragments. |
 | `standardize.clean` | schema_constraint_difference | `output` | See the JSON report for both schema fragments. |
 | `standardize.clean` | schema_constraint_difference | `preserve_line_breaks` | See the JSON report for both schema fragments. |

registry/schema/wrangle-entry.schema.json

@@ -188,10 +188,28 @@
             "Details"
           ]
         },
+        "column_semantics": {
+          "$ref": "#/$defs/column_semantics"
+        },
         "runtime_default": {},
         "schema": {"type": "object", "minProperties": 1}
       }
     },
+    "column_semantics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "cardinality"],
+      "properties": {
+        "role": {
+          "enum": ["reference", "destination"],
+          "description": "Whether the parameter selects columns that exist before the step or names columns where the step writes results."
+        },
+        "cardinality": {
+          "enum": ["scalar", "list", "scalar_or_list"],
+          "description": "Whether the parameter accepts one direct string/integer column identifier, an array whose direct items are string/integer identifiers, or either shape. Nullability is defined separately by the parameter schema; object and mapping-key locations require a future locator vocabulary."
+        }
+      }
+    },
     "example": {
       "type": "object",
       "additionalProperties": false,

registry/wrangles/_root/drop.md

@@ -34,10 +34,15 @@ parameters:
     description: Name of the column(s) to drop.
     required: true
     param_group: I/O
+    column_semantics:
+      role: reference
+      cardinality: scalar_or_list
     schema:
       type:
         - string
         - array
+      items:
+        type: string
 examples: []
 sources:
   - id: runtime

registry/wrangles/_root/rename.md

@@ -35,23 +35,35 @@ parameters:
     description: Name or list of input columns.
     required: false
     param_group: I/O
+    column_semantics:
+      role: reference
+      cardinality: scalar_or_list
     runtime_default: null
     schema:
       type:
         - string
         - integer
         - array
         - 'null'
+      items:
+        type:
+          - string
+          - integer
   - name: output
     description: Name or list of output columns.
     required: false
     param_group: I/O
+    column_semantics:
+      role: destination
+      cardinality: scalar_or_list
     runtime_default: null
     schema:
       type:
         - string
         - array
         - 'null'
+      items:
+        type: string
   - name: wrangles
     description: >-
       Use wrangles to transform the column names. The input is named 'columns' and the final result

registry/wrangles/extract/date-range.md

@@ -34,18 +34,27 @@ parameters:
     description: Name of the start date column.
     required: true
     param_group: I/O
+    column_semantics:
+      role: reference
+      cardinality: scalar
     schema:
       type: string
   - name: end_time
     description: Name of the end date column.
     required: true
     param_group: I/O
+    column_semantics:
+      role: reference
+      cardinality: scalar
     schema:
       type: string
   - name: output
     description: Name of the output column.
     required: true
     param_group: I/O
+    column_semantics:
+      role: destination
+      cardinality: scalar
     schema:
       type: string
   - name: range

registry/wrangles/standardize/clean.md

@@ -36,22 +36,36 @@ parameters:
     description: Name or list of input columns.
     required: true
     param_group: I/O
+    column_semantics:
+      role: reference
+      cardinality: scalar_or_list
     schema:
       type:
         - string
         - integer
         - array
+      items:
+        type:
+          - string
+          - integer
   - name: output
     description: Name or list of output columns. Defaults to overwriting input.
     required: false
     param_group: I/O
+    column_semantics:
+      role: destination
+      cardinality: scalar_or_list
     runtime_default: null
     schema:
       type:
         - string
         - integer
         - array
         - 'null'
+      items:
+        type:
+          - string
+          - integer
   - name: fix_encoding
     description: Repair mojibake and other reversible encoding errors.
     required: false

wrangles-docs/package.json

@@ -13,7 +13,8 @@
     "clear": "docusaurus clear",
     "compile:registry": "node ./scripts/compile-registry.cjs",
     "bootstrap:registry": "node ./scripts/bootstrap-registry.cjs",
-    "check:registry": "node ./scripts/compile-registry.cjs --check",
+    "test:registry": "node --test ./scripts/compile-registry.test.cjs",
+    "check:registry": "npm run test:registry && node ./scripts/compile-registry.cjs --check",
     "prebuild": "npm run compile:registry",
     "generate:wrangle-catalog": "node ./scripts/generate-wrangle-catalog.cjs",
     "serve": "docusaurus serve",