# Arxo population binding 0.1

An authoring, pinnable binding of microdata tables to the cases of a case package: the model and its semanticHash, the case package, a source as a closed CSV subset with tables, keys, entities, and parent-child relations, column-to-literal translation via TypeRef, the root population table (rowId, case name, weight, legalTime), and fact entries. It carries no legal meaning: the adapter computes nothing — each cell becomes a literal of an origin case_input fact. The contentHash self-pin is the canonical form without the contentHash field. The runner checks table and column name uniqueness, column existence in the header, and predicates and types against the CLIR (POPULATION_BINDING_INVALID / POPULATION_BINDING_MODEL_MISMATCH); the schema only holds the shape.

## Versions

Accepted `schemaVersion`: `law.population.binding/0.1`.

## Top-level fields

| name | type-or-$ref | required | description |
|---|---|---|---|
| `schemaVersion` | `"law.population.binding/0.1"` | yes | — |
| `id` | [`screen-binding.schema.json#/$defs/StableId`](/protocols/schemas/screen-binding/#stableid) | yes | — |
| `dataClass` | enum (2) | yes | Data class of the source: real triggers a POPULATION_BINDING_DATA_CLASS rejection pending a separate decision on storage. The field is required: its absence is not treated as synthetic. |
| `model` | `object` | yes | — |
| `casePackage` | `object` | yes | — |
| `source` | `object` | yes | — |
| `population` | `object` | yes | — |
| `facts` | `array` | yes | — |
| `contentHash` | [`screen-binding.schema.json#/$defs/Digest`](/protocols/schemas/screen-binding/#digest) | yes | — |

## Enumerations

| location | values |
|---|---|
| `properties/schemaVersion` | `"law.population.binding/0.1"` |
| `properties/dataClass` | `"synthetic"`, `"real"` |
| `properties/source/properties/encoding` | `"utf-8"` |
| `properties/source/properties/delimiter` | `","`, `";"`, `"\t"` |
| `properties/source/properties/decimalSeparator` | `"."`, `","` |
| `$defs/Parent/properties/cardinality` | `"one"`, `"many"` |
| `$defs/Fact/properties/presence/oneOf/0/properties/kind` | `"row"` |
| `$defs/Fact/properties/presence/oneOf/1/properties/kind` | `"boolean_column"` |
| `$defs/Argument/oneOf/0/properties/kind` | `"entity"` |
| `$defs/Argument/oneOf/1/properties/kind` | `"column"` |
| `$defs/Argument/oneOf/2/properties/kind` | `"constant"` |

## Raw schema

[`https://law.arxo.io/schema/population-binding.schema.json`](https://law.arxo.io/schema/population-binding.schema.json)

## `PackageName`

Type: `string`.

## `Version`

Type: `string`.

## `TableName`

Type: `string`.

## `ColumnName`

Name of a CSV header column.

Type: `string`.

## `Pattern`

Type: `object`.
Required: `pattern`.

| name | type-or-$ref | description |
|---|---|---|
| `pattern` | `string` | Text with {column} substitutions; the column's raw value — NULL triggers the row rejection ROW_KEY_NULL. |

## `ColumnRef`

Type: `object`.
Required: `column`.

| name | type-or-$ref | description |
|---|---|---|
| `column` | [`#/$defs/ColumnName`](#columnname) | — |

## `Table`

Type: `object`.
Required: `name`, `file`, `key`, `entity`, `columns`.

| name | type-or-$ref | description |
|---|---|---|
| `name` | [`#/$defs/TableName`](#tablename) | — |
| `file` | `string` | Path to the CSV relative to the binding file. |
| `key` | `array` | Key columns; uniqueness is a property of the source (POPULATION_SOURCE_INVALID). |
| `entity` | [`#/$defs/Entity`](#entity) | — |
| `parent` | [`#/$defs/Parent`](#parent) | — |
| `columns` | `array` | — |

## `Entity`

Type: `object`.
Required: `idPattern`, `type`.

| name | type-or-$ref | description |
|---|---|---|
| `idPattern` | `string` | Template for the row entity's identifier (URN/IRI) with {column} substitutions. |
| `type` | [`legal-ir.schema.json#/$defs/TypeRef`](/protocols/schemas/legal-ir/#typeref) | TypeRef of the model's nominal entity type; checked against the predicate's parameter. |

## `Parent`

Child table: the foreign key column points to the key of table table (a single-column key); an orphan triggers POPULATION_SOURCE_INVALID; more than one row when cardinality is one triggers the row rejection ROW_CARDINALITY.

Type: `object`.
Required: `table`, `column`, `cardinality`.

| name | type-or-$ref | description |
|---|---|---|
| `table` | [`#/$defs/TableName`](#tablename) | — |
| `column` | [`#/$defs/ColumnName`](#columnname) | — |
| `cardinality` | enum (2) | — |

## `Column`

Type: `object`.
Required: `name`, `type`.

| name | type-or-$ref | description |
|---|---|---|
| `name` | [`#/$defs/ColumnName`](#columnname) | — |
| `type` | [`legal-ir.schema.json#/$defs/TypeRef`](/protocols/schemas/legal-ir/#typeref) | TypeRef of a literal type (Integer, Decimal, Money, Boolean, Text, Date, Instant), or the name of a model enumeration (in which case members is required). |
| `currency` | `string` | Currency of a Money literal; required for Money, forbidden otherwise (checked by the tool). |
| `members` | `object` | Enumeration: source value → model member name. |
| `trueValues` | `array` | — |
| `falseValues` | `array` | — |
| `nullMarkers` | `array` | — |

## `Fact`

Type: `object`.
Required: `predicate`, `table`, `arguments`, `presence`.

| name | type-or-$ref | description |
|---|---|---|
| `predicate` | [`screen-binding.schema.json#/$defs/StableId`](/protocols/schemas/screen-binding/#stableid) | Identifier of the model's CLIR symbol_decl (a URN with a #local name). |
| `table` | [`#/$defs/TableName`](#tablename) | Table whose rows generate the fact; argument entities are this table or its ancestors along the parent chain. |
| `arguments` | `array` | — |
| `presence` | oneOf (2) | — |
| `required` | `boolean` | NULL in the column argument triggers the row rejection ROW_REQUIRED_NULL instead of the fact simply being absent. |

## `Argument`

Definition `Argument`.