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:.
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	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

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	—
pointer	#/$defs/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	—
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	—
pointer	#/$defs/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	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	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	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.