About Schemas

A schema is a named validation template that defines what fields a record's custom object must contain. When you create a wallet or anchor with a schema field, the ledger looks up that schema's definition and validates the custom object against it before accepting the record. Schemas enforce data quality at creation time — the errors surface during onboarding, not during a live payment.

What a schema is

Every wallet and anchor can carry a custom object — an open bag of key-value fields for whatever domain data the record needs. A merchant wallet needs a business name, city, and tax regime. A settlement wallet needs a bank code and account type. A QR anchor needs a payment target.

Without schemas, the ledger accepts any custom content and any downstream error shows up when a bridge tries to generate a payload and finds a missing field. The bridge can't compute the MCC because there's no category. The tax block is wrong because taxRegime was never set. The settlement account doesn't exist because settlement was a typo.

Schemas move that validation earlier. When you attach a schema to a record, the ledger knows what fields are required, what types they must be, and what values are valid. A record that fails validation is rejected at POST time with a clear error. Nothing broken gets stored.

Built-in schemas

The platform ships with schemas for the most common use cases. These are deployed as part of the ledger's initial setup — via layout files or manual creation — and are available to use immediately.

merchant-wallet — the full business identity for a merchant participant. It requires name, city, taxId, category, country, taxRegime, settlement, and type. The bridge reads every one of these fields when generating a QR payload or registering an alias: category maps to an MCC, taxId determines the alias type, country selects the national EMVco profile, taxRegime controls the tax block, and settlement tells the bridge where to credit incoming funds. A merchant parent wallet carries all of these. A store wallet (a child in the same domain) carries only name, city, postal, and type: "store" — the bridge walks up to the domain's main@ wallet for the rest.

{
  "handle": "main@starbucks.com",
  "schema": "merchant-wallet",
  "custom": {
    "name": "STARBUCKS COLOMBIA",
    "city": "BOGOTA",
    "taxId": "900123456-7",
    "category": "Fast food restaurant",
    "country": "CO",
    "taxRegime": "standard",
    "settlement": "svgs:4242@bank.co",
    "type": "merchant"
  }
}

settlement-wallet — the ledger representation of a real bank account. It requires name, type, bankCode, and accountType. When an ACH bridge sees a wallet carrying this schema, it knows the wallet maps to an external account and must go through two-phase commit with the real bank.

{
  "handle": "svgs:4242@bank.co",
  "schema": "settlement-wallet",
  "bridge": "bridge@achcolombia.com.co",
  "custom": {
    "name": "Starbucks Settlement Account",
    "type": "settlement",
    "bankCode": "007",
    "accountType": "savings"
  }
}

qr-static — the minimal anchor schema for a permanent QR code. It requires only handle and target. The bridge fills in everything else by reading the wallet the anchor points to. Because the schema is qr-static, the bridge sets point-of-initiation to 11 (reusable), embeds no amount, and the customer enters the total themselves when they scan.

{
  "handle": "qr0000001@starbucks.com",
  "schema": "qr-static",
  "target": "store1@starbucks.com"
}

qr-dynamic — the anchor schema for a per-transaction QR with a fixed amount. It requires handle, target, amount, and symbol. The bridge reads these fields to encode the checkout total in EMVco Tag 54 and sets point-of-initiation to 12 (one-time). The code expires once the payment settles.

{
  "handle": "qr0000099@starbucks.com",
  "schema": "qr-dynamic",
  "target": "store1@starbucks.com",
  "amount": "1500000",
  "symbol": { "handle": "cop" }
}

How schemas work

When you POST a wallet or anchor with a schema field, the ledger looks up that schema's definition and validates the custom object against its rules. Required fields must be present. Typed fields must match their declared type. Fields that the schema doesn't recognize may be rejected or flagged depending on how the schema is configured.

If validation fails, the ledger returns an error before the record is stored. The error message names the specific field that failed — missing, wrong type, or unrecognized. This catches configuration mistakes at onboarding time: a misspelled bankCode, a missing taxRegime, a type value the bridge doesn't recognize.

The alternative — no schema, open-ended custom, validation deferred to runtime — means a misconfigured merchant wallet can sit quietly in the ledger for weeks until a QR payment attempt reveals that the bridge can't resolve the MCC because category was never set. Schemas make that impossible.

Schema-driven bridge behavior

Schemas don't just validate data — they tell bridges what processing to apply. The schema on a record is the bridge's dispatch key.

When a bridge sees an anchor created with schema: "qr-static", it knows to generate a reusable EMVco payload. It sets point-of-initiation to 11, generates no amount tag, and produces a code that can be scanned unlimited times. When it sees schema: "qr-dynamic", it does something different: it encodes the amount in Tag 54, sets point-of-initiation to 12, and marks the code as single-use.

The same pattern applies to settlement. When an intent involves a wallet carrying schema: "settlement-wallet", the ACH bridge knows that wallet maps to a real external account. It initiates two-phase commit with the banking network — a debit on the real account mirrors the ledger debit before the intent commits. A wallet without that schema doesn't trigger that behavior.

This means schemas are not passive metadata. They are the mechanism by which bridges select behavior. Adding a new schema to a ledger is adding a new processing mode — a new way for bridges to respond to a type of record.

Custom schemas

Operators can define their own schemas for cases that the built-in ones don't cover. A cross-border remittance schema might require beneficiaryCountry, bankRoutingNumber, and purposeOfPayment. A subscription billing schema might add billingCycle and renewalDate. A corporate treasury schema might require costCenter, glAccount, and approvalLevel.

Custom schemas are records on the ledger, created via the API or CLI like any other resource. Once deployed, they're available to use in wallet and anchor creation the same way built-in schemas are. Bridges built to recognize them can dispatch on their values — a remittance bridge checks for purposeOfPayment and selects the correct SWIFT category code; a billing bridge reads billingCycle to determine the settlement frequency.

The design is intentional. The ledger is not opinionated about what your custom fields mean — that meaning lives in the schema and in the bridge that reads it. Adding a domain to the ledger means defining its schema, deploying it, and connecting a bridge that understands it.

Where schemas are deployed

Schemas live on the ledger itself. They must be created before the wallets and anchors that reference them — a wallet creation that references an unknown schema fails validation immediately.

In practice, schemas are part of the ledger's initial setup. A layout file (a configuration blueprint applied when the ledger is provisioned) typically creates all the schemas the ledger needs before any participant wallets or payment anchors are created. This means schemas are always present when you start onboarding merchants or creating QR codes.

You can inspect what schemas are available on a ledger at any time:

minka schema list

The output lists every schema by handle along with its field definitions. If a schema is missing or has changed, you'll see it here before it causes a validation error downstream.

Next steps

• How to Onboard a Merchant — merchant-wallet and settlement-wallet schemas in action, with the full field reference
• How to Collect with a Static QR — how the qr-static schema controls what the bridge generates and embeds in the payload