Canonical Field Registry

The canonical field registry — defined in packages/core-model/src/canonical/field-registry.ts and exposed at GET /v1/canonical-fields — is the single source of truth for “what fields exist on each canonical model, and which evidence sources can populate them.” External files, webhooks, and APIs should map into these known fields. Unknown or long-tail data should stay in RawRecord.payload, metadata, or FlowLegReference — never invent ad-hoc canonical columns at runtime.

Purpose

The registry gives three parts of the product a shared contract:

Import profile builders know which fields can be mapped (fieldMappings on ImportProfile).
API and adapter code know which canonical shape to produce when normalizing a RawRecord into a FlowLeg or PaymentIntent.
Dashboard screens know which fields to show when users configure mappings.

The `/v1/canonical-fields` endpoint

GET /v1/canonical-fields?model=<CanonicalFieldModel>&sourceType=<CanonicalFieldSourceType>&importTargetsOnly=<boolean>

Query parameters (CanonicalFieldListQuery):

Param	Type	Behavior
`model`	`PaymentIntent \| RawRecord \| FlowLeg \| FlowLegReference \| ReconciliationCase`	Filter to fields on one model.
`sourceType`	`CanonicalFieldSourceType`	Filter to fields whose `sourceTypes` includes this value.
`importTargetsOnly`	`boolean` (default `false`)	When `true` and `sourceType` is set, returns only fields valid as import mapping targets for that source type (see below). When `true` without a `sourceType`, returns an empty list.

Each item in the response (CanonicalFieldDefinitionResponse):

{
  path: string;            // e.g. "PaymentIntent.sourceAmount"
  model: string;
  label: string;
  description: string;
  requirement: 'required' | 'optional' | 'system';
  storage: 'first_class' | 'json' | 'reference';
  sourceTypes: string[];
  examples?: string[];
  notes?: string;
}

`requirement` values

required — must be present for the model to be valid (e.g. PaymentIntent.externalReference, RawRecord.payload, FlowLeg.type).
optional — may be present; enriches matching, reporting, or review.
system — written by the matcher/evaluator, not by import mappings. All ReconciliationCase.* fields are system.

`storage` values

first_class — a real column on the table (queryable, indexable).
json — stored inside a Json column (metadata, references, payload, validationErrors).
reference — stored as a row in FlowLegReference (typed key/value identifiers).

`CanonicalFieldSourceType` values

client_transfer_report   client_internal_ledger   bank_statement
onchain_report            psp_report                manual
api_expectation

api_expectation represents direct API intake (POST /v1/payment-intents, POST /v1/evidence/provider, POST /v1/evidence/onchain) — it is excluded from ReconciliationRule.sourceType (a rule can’t be scoped to “the API itself” as an evidence source) but is a valid sourceTypes entry for PaymentIntent fields.

`PaymentIntent` fields

Populated by direct API intake (api_expectation) or client_internal_ledger file imports.

Field path	Requirement	Storage	Description	Examples / Notes
`PaymentIntent.externalReference`	required	first_class	Client’s stable business reference for the expected payment	Used for business idempotency within an organization
`PaymentIntent.sourceAmount`	required	first_class	Expected amount leaving the source side	`1000.00`
`PaymentIntent.sourceCurrency`	required	first_class	Currency or token expected on the source side	`USD`, `USDC`
`PaymentIntent.destinationAmount`	required	first_class	Expected amount at the beneficiary/destination side	`82500.00`
`PaymentIntent.destinationCurrency`	required	first_class	Currency or token expected at the destination side	`INR`, `MXN`, `USDC`
`PaymentIntent.paymentType`	optional	first_class	Broad payment category	`stablecoin`, `bank`, `cross_border`, `other`
`PaymentIntent.paymentSubtype`	optional	first_class	Narrow rail, corridor, or provider subtype	`wire`, `swift`, `usd_mxn`, `polygon_usdc`
`PaymentIntent.direction`	optional	first_class	Direction from the client’s perspective	`debit`, `credit`
`PaymentIntent.effectiveDate`	optional	first_class	Business effective date for the expected payment	Not the same as ingestion time
`PaymentIntent.beneficiaryAccount`	optional	first_class	Destination account, wallet, or payout identifier
`PaymentIntent.beneficiaryName`	optional	first_class	Beneficiary display name
`PaymentIntent.stablecoin`	optional	first_class	Token symbol when the expectation is stablecoin-specific	`USDC`
`PaymentIntent.chain`	optional	first_class	Chain or network label when known	`polygon`
`PaymentIntent.references`	optional	json	Structured references attached to the expected payment	Not an import mapping target — excluded from import mapping
`PaymentIntent.metadata`	optional	json	Client-specific context not part of standard matching	`cost_center`, `batch_id`, `corridor`. Not an import mapping target

Both sourceTypes for every PaymentIntent field are ['client_internal_ledger', 'api_expectation'].

`RawRecord` fields

Populated for every ingested record before normalization, from any evidence source type (client_transfer_report, client_internal_ledger, bank_statement, onchain_report, psp_report, manual).

Field path	Requirement	Storage	Description	Examples / Notes
`RawRecord.source`	required	first_class	Ingestion channel	`file`, `api`, `webhook`, `manual`
`RawRecord.sourceType`	optional	first_class	Business category of the source	e.g. `bank_statement`, `psp_report`, `onchain_report`
`RawRecord.provider`	optional	first_class	Vendor or provider label	`bridge`, `bvnk`, `icici`, `alchemy`. Not valid for `client_transfer_report`/`client_internal_ledger`
`RawRecord.integrationKey`	optional	first_class	Technical connector identity	`bridge:webhook`, `icici:daily-xlsx`. Same source-type restriction as `provider`
`RawRecord.sourceRef`	required	first_class	Stable source-side identifier	provider id, tx hash, file row id
`RawRecord.payload`	required	json	Untouched source payload	Never edited; not an import mapping target
`RawRecord.rowNumber`	optional	first_class	Source row number for files	Used for row-level import feedback. Not valid for `manual`

`FlowLeg` fields

Populated when the source represents actual money movement: bank statement row, PSP/provider transfer event, on-chain transfer event, or payout confirmation.

Field path	Requirement	Storage	Description	Examples / Notes
`FlowLeg.type`	required	first_class	Type of actual money movement	`provider_transfer`, `onchain_transfer`, `bank_transfer`
`FlowLeg.phase`	optional	first_class	Role of the leg inside a multi-step route	`source`, `intermediary_in`, `transfer`, `intermediary_out`, `destination`
`FlowLeg.status`	optional	first_class	Status of this movement leg	`pending`, `confirmed`, `failed`, `reversed`, `missing`
`FlowLeg.reconciliationScope`	optional	first_class	Whether this leg is required, optional, or ignored for completeness	`required`, `optional`, `ignored`
`FlowLeg.routeGroupId`	optional	first_class	Groups legs that belong to one route or retry path
`FlowLeg.sequence`	optional	first_class	Order of this leg inside a route group
`FlowLeg.providerTransferId`	optional	first_class	High-value provider transfer identifier	Valid for `client_transfer_report`, `psp_report`, `manual`
`FlowLeg.txHash`	optional	first_class	On-chain transaction hash	Valid for `onchain_report`, `psp_report`, `manual`
`FlowLeg.chainId`	optional	first_class	Numeric chain identifier	`137`. Valid for `onchain_report`, `psp_report`, `manual`
`FlowLeg.fromAddress`	optional	first_class	On-chain sender address	Valid for `onchain_report`, `manual`
`FlowLeg.toAddress`	optional	first_class	On-chain receiver address	Valid for `onchain_report`, `manual`
`FlowLeg.tokenAddress`	optional	first_class	Token contract address	Valid for `onchain_report`, `manual`
`FlowLeg.provider`	optional	first_class	Vendor or provider label for the normalized leg	Not valid for `client_transfer_report`
`FlowLeg.integrationKey`	optional	first_class	Technical connector identity for the normalized leg	Same restriction as `provider`
`FlowLeg.amount`	optional	first_class	Amount moved on this leg
`FlowLeg.currency`	optional	first_class	Currency or token moved on this leg	`USD`, `USDC`, `INR`
`FlowLeg.occurredAt`	optional	first_class	When the movement happened
`FlowLeg.metadata`	optional	json	Extra leg context not part of standard matching	Not an import mapping target

FlowLeg.type, .phase, .status, .reconciliationScope, .routeGroupId, .sequence, .amount, .currency, .occurredAt, and .metadata all share sourceTypes: ['client_transfer_report', 'bank_statement', 'onchain_report', 'psp_report', 'manual'].

`FlowLegReference` fields — typed long-tail identifiers

Use FlowLegReference for identifiers that should be searchable but shouldn’t become new nullable columns on FlowLeg.

Field path	Requirement	Storage	Description	Examples
`FlowLegReference.type`	required	reference	Identifier type for long-tail leg references	`bank_reference`, `ach_trace_number`, `uetr`, `sepa_reference`
`FlowLegReference.value`	required	reference	Identifier value for long-tail leg references

Typed reference mapping target: `FlowLegReference.<referenceType>`

Import profiles can target FlowLegReference.<referenceType> (e.g. FlowLegReference.bank_reference, FlowLegReference.uetr) directly. This is a synthetic mapping target — getSupportedImportMappingTargetsForSourceType() adds it for every source type that supports FlowLegReference.

Legacy normalization: mapping targets of the form references.<type> (e.g. references.bank_reference) are automatically normalized to FlowLegReference.<type> by normalizeImportMappingTargetPath(). New mappings should use the FlowLegReference.<type> form directly.

`ReconciliationCase` fields — system-written, not import targets

These fields are written by the matcher/evaluator (apps/api/src/services/matcher.ts), never by import mappings. All have requirement: 'system' and are excluded from getSupportedImportMappingTargetsForSourceType().

Field path	Description	Written from
`ReconciliationCase.expectedAmount`	Expected case amount, usually copied from `PaymentIntent.sourceAmount`	Set when the case is created
`ReconciliationCase.actualAmount`	Observed reconciled amount	The selected leg’s `amount` (`selectCaseEvaluationLeg`)
`ReconciliationCase.providerFee`	Provider fee component for delta breakdown	`payload.event_object.receipt.developer_fee`, or prior value
`ReconciliationCase.networkFee`	Network/chain fee component for delta breakdown	`payload.event_object.receipt.gas_fee`, or prior value
`ReconciliationCase.developerFee`	Platform/developer fee component for delta breakdown	Prior value (not refreshed by the matcher today)
`ReconciliationCase.fxSpread`	FX variance/spread component for delta breakdown	`payload.event_object.receipt.exchange_fee`, or prior value
`ReconciliationCase.roundingDelta`	Rounding component for delta breakdown	Prior value (not refreshed by the matcher today)
`ReconciliationCase.unexplainedDelta`	Remaining unexplained amount after known deltas	`reconcile()` output — the key ops review field

sourceTypes for these fields reflects which evidence kinds can plausibly produce the underlying fee data: providerFee/developerFee ← psp_report/manual; networkFee ← onchain_report/manual; fxSpread/roundingDelta ← client_transfer_report/psp_report/manual; expectedAmount ← client_internal_ledger/api_expectation; actualAmount/unexplainedDelta ← any evidence source type.

Import mapping target rules

isSupportedImportMappingTarget(sourceType, path) decides whether a path is a valid value in ImportProfile.fieldMappings for a given sourceType. A path is valid if:

It’s a canonical field whose sourceTypes includes the requested sourceType, and it is not in the import-mapping-excluded set (PaymentIntent.references, PaymentIntent.metadata, RawRecord.source, RawRecord.payload, RawRecord.rowNumber, FlowLeg.metadata, FlowLegReference.type, FlowLegReference.value, and every ReconciliationCase.* field), or
It normalizes (via normalizeImportMappingTargetPath) to FlowLegReference.<referenceType> with a non-empty referenceType, and that source type supports FlowLegReference as a mapping target.

`ImportSourceType` → primary downstream model

`ImportSourceType`	Primary downstream target
`client_internal_ledger`	`PaymentIntent` and `ReconciliationCase` (expectation-first)
`client_transfer_report`	Usually `FlowLeg`, sometimes supporting evidence
`bank_statement`	`FlowLeg` (evidence-first)
`psp_report`	`FlowLeg` (evidence-first)
`onchain_report`	`FlowLeg` (evidence-first)
`manual`	Depends on manual entry type

List canonical fields

GET /v1/canonical-fields API reference.

Core Concepts

What each model represents in the reconciliation lifecycle.

​Purpose

​The /v1/canonical-fields endpoint

​requirement values

​storage values

​CanonicalFieldSourceType values

​PaymentIntent fields

​RawRecord fields

​FlowLeg fields

​FlowLegReference fields — typed long-tail identifiers

​Typed reference mapping target: FlowLegReference.<referenceType>

​ReconciliationCase fields — system-written, not import targets

​Import mapping target rules

​ImportSourceType → primary downstream model

List canonical fields

Core Concepts

Purpose

The `/v1/canonical-fields` endpoint

`requirement` values

`storage` values

`CanonicalFieldSourceType` values

`PaymentIntent` fields

`RawRecord` fields

`FlowLeg` fields

`FlowLegReference` fields — typed long-tail identifiers

Typed reference mapping target: `FlowLegReference.<referenceType>`

`ReconciliationCase` fields — system-written, not import targets

Import mapping target rules

`ImportSourceType` → primary downstream model