# Arxo Fact Protocol source mapping 0.1

An authoring-time, pinnable declaration of how ONE external record — a database row, a bus event, a form submission, an API response, serialized as a JSON document — becomes facts of the Arxo Fact Protocol. It names the model and its semantic hash; the record scopes addressed by JSON Pointer (RFC 6901) with the entity each scope instance denotes; typed fields; fact entries; provenance; and an optional evidence document for the record itself. It carries no semantics: the mapping computes nothing — each field value becomes a typed model term of a fact with declared origin, and the record becomes the evidence item the facts point to. The output is a fact set. The contentHash self-pin excludes its own field. The tool checks scope and field names, pointers, predicates, and types against the compiled model, reporting mapping errors; the schema holds only the shape. Tabular microdata stay with the population binding.

## Versions

Accepted `schemaVersion`: `law.source-mapping/0.1`.

## Top-level fields

| name | type-or-$ref | required | description |
|---|---|---|---|
| `schemaVersion` | `"law.source-mapping/0.1"` | yes | — |
| `id` | `string` | yes | Mapping identifier; the extractor name of every emitted fact is source-mapping:<id>. |
| `description` | `string` | no | Free text for the reader: which system, table, topic or form the record comes from. Not read by the tool. |
| `model` | `object` | yes | — |
| `scopes` | `array` | yes | Parts of the record that denote entities. Exactly one root scope (no parent); every other scope names its parent, and the parent chain reaches the root. |
| `facts` | `array` | yes | — |
| `provenance` | `object` | no | Provenance shared by every emitted fact. origin defaults to case_input; extraction is not a new origin. |
| `evidence` | `object` | no | The record as an evidence item: every emitted fact points to it, and its document hash is the sha256 of the exact record bytes. Without this section facts carry no document, and the core warns FACT_WITHOUT_EVIDENCE — the honest signal that the record itself was not presented. |
| `contentHash` | [`screen-binding.schema.json#/$defs/Digest`](/protocols/schemas/screen-binding/#digest) | yes | — |

## Enumerations

| location | values |
|---|---|
| `properties/schemaVersion` | `"law.source-mapping/0.1"` |
| `properties/provenance/properties/origin` | `"case_input"`, `"source_asserted"`, `"external_snapshot"`, `"adjudicated"`, `"assumed_for_simulation"` |
| `$defs/Fact/properties/presence/oneOf/0/properties/kind` | `"always"` |
| `$defs/Fact/properties/presence/oneOf/1/properties/kind` | `"boolean_field"` |
| `$defs/Argument/oneOf/0/properties/kind` | `"entity"` |
| `$defs/Argument/oneOf/1/properties/kind` | `"field"` |
| `$defs/Argument/oneOf/2/properties/kind` | `"constant"` |

## Raw schema

[`https://law.arxo.io/schema/source-mapping.schema.json`](https://law.arxo.io/schema/source-mapping.schema.json)

## `Name`

Type: `string`.

## `Pointer`

JSON Pointer (RFC 6901). The empty string is the element itself.

Type: `string`.

## `IdPattern`

Text with {pointer} substitutions, where pointer is a JSON Pointer relative to the scope element ({/id}) or, prefixed with $, absolute from the record root ({$/tenant}). The substituted value must be a string or an integer; null or missing triggers RECORD_KEY_NULL. The result must be a URN or IRI.

Type: `string`.

## `Scope`

Type: `object`.
Required: `name`, `pointer`, `entity`.

| name | type-or-$ref | description |
|---|---|---|
| `name` | [`#/$defs/Name`](#name) | — |
| `pointer` | [`#/$defs/Pointer`](#pointer) | Root scope: absolute pointer to an object (the record must have it, otherwise SOURCE_RECORD_INVALID). Child scope: pointer relative to the parent element. |
| `parent` | [`#/$defs/Name`](#name) | — |
| `each` | `boolean` | Child scope only. true: the pointer addresses an array, each element is one instance (null or missing is zero instances). false (default): the pointer addresses one object (null or missing is no instance). |
| `entity` | `object` | — |
| `fields` | `array` | — |

## `Field`

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

| name | type-or-$ref | description |
|---|---|---|
| `name` | [`#/$defs/Name`](#name) | — |
| `pointer` | [`#/$defs/Pointer`](#pointer) | Pointer relative to the scope element. JSON null or a missing member is absence of the value. |
| `type` | [`legal-ir.schema.json#/$defs/TypeRef`](/protocols/schemas/legal-ir/#typeref) | TypeRef: urn:law:std#Integer, Decimal, Money, Boolean, Text, Date, Instant, or an enum of the model. |
| `currency` | `string` | Money only, exclusive with currencyPointer: ISO 4217 code of every value. |
| `currencyPointer` | [`#/$defs/Pointer`](#pointer) | Money only, exclusive with currency: pointer relative to the scope element to a three-letter code. |
| `members` | `object` | Enum only: source value (a string, or the decimal text of an integer) to member name. Non-empty, every value a non-empty string: the tool checks it (SOURCE_MAPPING_INVALID), so every runner validates one keyword set. |
| `trueValues` | `array` | Boolean only: strings read as true, in addition to JSON true. |
| `falseValues` | `array` | Boolean only: strings read as false, in addition to JSON false. |
| `nullValues` | `array` | Strings read as absence, in addition to JSON null (for instance an empty string of a form). |

## `Fact`

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

| name | type-or-$ref | description |
|---|---|---|
| `predicate` | `string` | symbol_decl id of a relation of the model (URN with #). |
| `scope` | [`#/$defs/Name`](#name) | Scope whose instances emit the fact: one fact per instance. |
| `arguments` | `array` | — |
| `presence` | oneOf (2) | — |
| `required` | `boolean` | An absent field argument refuses the whole record (RECORD_REQUIRED_NULL) instead of dropping the fact. Default false. |

## `Argument`

Definition `Argument`.

## `InstantSource`

Definition `InstantSource`.