Ops API

The standard says what a funding pack must prove. This is the API a firm uses to produce one — cases, checklists, chasing, and the audit trail underneath. Two halves of the same argument.

Authentication and scoping

A broker signs in by one-time code; the session is a signed vouch_broker_session cookie. Every request resolves to a firm (org) and a user.

• 401 — no valid session.
• 404 — the case is not in your firm. Deliberately not 403: a 403 would confirm that a case with that id exists somewhere, which discloses one firm's book to another. Absence of disclosure is the point.

Org scoping is enforced in the data layer, not the UI. There is no query path that returns another firm's case.

The case lifecycle

collecting → checking → ready → submitted, plus closed. Transitions are validated server-side; closed is terminal. An invalid transition is a 400 with a reason, never a silent no-op.

Derived fields — the ones the queue is built on

Every case carries four computed values. They are computed server-side on purpose: two implementations of one rule is how a board and a work queue start disagreeing about what needs doing.

A case needs a human when ball_with === "broker" OR it is stale beyond its threshold, whoever holds it. The second half matters: a case sitting with the borrower for ten days is not "fine, we're waiting" — it means the chase has failed, which is exactly when a person should step in.

The work queue

GET /broker/queue returns only cases needing a human, ordered: yours, then unassigned, then colleagues' — and within each band, breached first, worst overrun first, then oldest.

Two deliberate choices worth knowing before you build on it. Unassigned outranks a colleague's work, because a case nobody has picked up is the one most likely to be dropped. And ownership outranks a breach — this is a personal work queue, not a firm dashboard; if a colleague's emergency reordered your list, nobody could trust the top of it. Firm-wide breach counts are separate.

The audit trail

GET /broker/cases/{id}/events — append-only, chronological. Nothing rewrites history.

• case_created, status_changed, item_added, item_status_changed, item_waived
• chase_sent, chase_blocked — including why a chase did not go
• case_assigned — carries the previous owner, because "who was responsible on the day" cannot be reconstructed from the current value
• case_reviewed_no_action — a human looked and decided nothing was needed. It changes nothing about the case, deliberately: it does not even touch updated_at, because that would reset staleness and make an untouched case look freshly worked. "Nobody flagged it" and "somebody looked and judged it fine" are different facts, and only the second is oversight.

Extending it — the three adapter families

Adding a provider means registering a class. Nothing else changes.

1. LenderAdapter — one pack out to a lender's own schema. Where a lender has no API, the same pack becomes a pre-filled deal sheet by email.
2. ContactChannelAdapter — how the borrower is reached. Email routes through a single suppression and unsubscribe choke point.
3. SourceAdapter — verified facts in, from the system that witnessed the work. Pay-per-search sources route through a shared control layer enforcing consent, an explicit payer, metering and idempotency.

Integration shape, stated plainly

Polling, not webhooks. There is no event push today. A consumer polls /broker/queue or the case endpoints. Saying so is better than implying an event stream that would have to be built after you designed against it.

AgenticFunding

framework · draft · open by design

AgenticFunding is a platform architecture for agent-operated loan origination. Origination today runs through people and loses information along the way. A borrower or broker assembles a case by hand. The funder re-underwrites nearly all of it because the file itself gives the funder no way to trust any of it. This duplicated checking adds cost at every step.

The AgenticFunding model assigns that work to an origination agent, the AgenticFunder. The agent gathers what a case needs. It verifies facts against public registries. It chases what's missing. It collects the applicant's declarations. It assembles the result into a deal package, the framework's final output. The deal package reaches funders in a form their systems can consume and their underwriters can rely on for triage.

The agent proposes; provenance and deterministic gates dispose.

One v0 limitation applies to every claim on this page: provenance is the producer's recorded claim, not yet a proof a third party can check. The trust boundary states this in full.

The design constraint that makes agentic origination viable in regulated finance is that the agent never asks to be trusted. Every fact it hands over carries its provenance: verified, self-declared, document-backed, or honestly not-collected. The funder's own deterministic gates and human underwriting make every decision. Nothing in the framework asks anyone to act on model output.

The stack

The Reference architecture holds the full facet map (glossary, capability, entity, process, data-dictionary and C4 views). The Platform architecture documents the component decomposition. The standard specifies the output contract. Credit teams should start at For credit teams. Implementers and funders can download the artifacts and participate.

For credit teams

what a funder receives, what it still has to do, and how to run a pilot

This page is for the people who read the file and make the decision. It states what a conforming pack gives a credit team, what the pack does not give them, and what the team still carries.

What you receive

What the pack does not give you

• It is not a credit decision. The standard carries no score, no ranking and no recommendation. Your gates and your underwriters decide.
• Oven-ready does not mean verified. status answers whether every required field is present. conformance_level answers how the facts were established. Read both, and read the provenance mix on the summary sheet.
• Provenance is a claim, not yet a proof. In v0 the producer records how each fact was established. A consumer cannot independently verify that record. Trusting a pack means trusting its producer, which is why a pack names its producer and their regulatory status. Signed evidence anchors are the roadmap item that closes this gap.

What your firm still carries

• Customer due diligence. Screening results in a pack are informational. They do not discharge your own obligations under the Money Laundering Regulations 2017. Relying on another firm's checks requires an explicit regulation-39 arrangement.
• Your own freshness policy. Validation is deliberately clock-free. Each verified fact carries the date it was checked. Your firm sets how old is too old.
• Spot-verification of what matters. The pack replaces re-collection and triage. It does not replace verification of the facts your credit policy turns on.
• Data protection. Packs carry personal data about directors and guarantors. A firm receiving a pack is a controller in its own right under UK GDPR.
• A secure channel. The standard is transport-neutral. Agree the channel before exchanging packs that carry personal data.

Wiring your gates

A credit team consumes a pack in three passes. Pass one is mechanical: run the reference validator, or your own implementation checked against the published conformance vectors, and reject anything that does not conform. Pass two is policy: read readiness.missing, the conformance level and the provenance mix against your appetite, and return an info_requested disposition for anything you need. Pass three is underwriting, unchanged.

Running a pilot

1. Read one pack. Take the worked example and the rendered summary. Decide whether the fields you underwrite on are present, and tell us what is missing for your product.
2. Shape the requirement profile. Requirement profiles say what evidence a product needs before a pack may claim readiness. Profiles are published as drafts and go through a public comment window under the charter, so your input becomes part of the standard rather than a private arrangement.
3. Receive live packs and reply with dispositions. This closes the loop and is the point at which the standard is proven in practice.

Contact: [email protected]. See also Participate and the regulatory notes.

Reference architecture

the facet map + C4 level 1 (system context) · source: docs/deal-schema/c4-context.mmd

A reference architecture is the set of views that lets any implementer build a conforming platform without reading the reference code. The same views let any funder integrate a conforming platform. Mature industry data standards use the same structure: a set of linked views (facets). Each facet answers one question. Each facet is usable alone or in combination with the others. The framework defines seven facets:

The architecture views use the C4 model. Level 1 (system context) appears below and shows who and what surrounds the platform. Level 2 (container) is the Platform architecture page. Levels 3–4 (component/code) are deliberately not published: they describe one particular implementation. Any conforming implementation may occupy the platform role.

System context (C4 level 1)

The platform element in the diagram is deliberately generic. The protocol (the open standard) is the only coupling between an origination platform and a funder. The reference implementation demonstrates that a conforming platform can be built; it holds no privileged position in the framework.

Platform architecture

C4 level 2 — the container view of the reference architecture

This page describes the containers of the AgenticFunder platform. Every capability below runs in the reference implementation (AskVouch).

Every fact carries provenance. Nothing is ever fabricated.

Capability → component map

Platform properties

• Deterministic-first. Verdicts, gates and chase timing are pure functions; the LLM assists with conversation, never with credit decisions or verified facts.
• Append-only audit. Every case action is an event in an append-only log; state is derived, so the system is restart-safe and fully auditable.
• Honest absence. A fact the platform did not establish is marked not-collected. The pack never presents a missing fact as established.
• Operating modes. Broker-in-the-loop is the current mode: the agent is the broker's ops teammate. Broker-optional operation runs only under an authorised principal. The regulatory boundary is stated explicitly (see Regulatory notes).

Capability model

The capability model breaks the origination value chain into capabilities with no fixed order. A capability is a thing the platform must be able to do. The model is deliberately not a fixed workflow. Facilities compose these capabilities differently. Example: a term loan runs the chain once; a continuous-mode receivables facility loops gather → verify → submit → dispose for the life of the facility. Each capability names the component in the reference implementation (AskVouch) that provides it today, and the protocol artifact it produces or consumes.

Platform architecture covers how the agent-side capabilities are wired. Lending coverage covers which profile selects which evidence.

The deal-package standard

Standard lending-deal-package-readiness · schema https://askvouch.com/schemas/deal-package-readiness/v0.5.0/deal-package.schema.json · draft v0.4

The deal package is the final output of the AgenticFunding framework — the artifact the agent delivers to funders. This section specifies it as an open, machine-readable standard: what a funding case contains, where each fact came from (provenance), and whether the pack is ready to submit (a readiness verdict with conformance levels). It complements open-data initiatives on the submission side by defining shared readiness in addition to shared data.

What is normative

• The JSON Schemas (deal-package.schema.json — the pack shape; deal-package.strict.schema.json — a generated companion that enumerates the full vocabulary, for consumers who can only run plain JSON Schema).
• The disposition message (disposition.schema.json), which is the funder's machine-readable response, and the borrowing-base certificate (continuous mode).
• The conformance vectors (conformance-vectors.v0.json) — 30 published test cases any implementation can run.
• The field catalogue / data dictionary (field-catalogue.v0.json) — which fields may appear: datatype, definition, tag, source, data class, and the baseline requirement profile.
• The code lists (code-lists.v0.json) — versioned enumerations; enum-valued fields must carry a listed code.
• The requirement profiles (requirement-profiles.v0.json) — per-product required evidence + readiness mode, selected by the_ask.facility_type.
• The reference-data registry (reference-data.v0.json) — the external registries verified facts cite.
• The readiness rules (readiness & conformance) — enforced by the reference validator.

Everything else on this site is explanatory. Terminology follows RFC-2119-style usage (MUST / SHOULD / MAY) where capitalised.

Status & licences

• Draft v0.4. Working name; final naming is pending clearance.
• Schema and code: Apache-2.0. Specification prose: CC-BY-4.0. Upstream attributions in NOTICE.
• Source of truth: docs/deal-schema/ in the AskVouch repository (schema, catalogue, validator, fixtures, crosswalks, governance files).

Lending coverage

facility_type: 16 products · profiles_version 0.7.0

The standard covers the full range of debt products through three mechanisms: the facility_type taxonomy (the product classification; use_of_funds classifies purpose), per-product requirement profiles (what evidence each product needs before a pack may claim oven-ready), and product-specific catalogue sections (receivables for invoice finance/factoring/ABL, capital_structure for mezzanine, development for development finance, trade_finance for import/export facilities, card_receipts for merchant cash advances).

The status column records each product's maturity: v0 = profiled and stable; draft = profiled, published as a draft and open for comment under the charter; taxonomy-only = named in the product list, but its evidence checklist is not written yet. Packs for it fall back to the baseline requirements. The taxonomy-only status records this gap explicitly.

Profile selection

The pack's the_ask.facility_type value selects the profile whose applies_to contains it; packs without a facility type use baseline-v0 (the catalogue's required_fields). The reference validator enforces this selection. Example: an invoice-finance pack cannot claim oven-ready without its debtor book, and a mezzanine pack cannot claim it without the capital stack.

One-shot vs continuous readiness

Term products are underwritten one-shot: the pack is submitted once. Receivables-backed revolving products (readiness_mode: continuous) use this pack for onboarding, then operate on recurring borrowing-base certificates. The latest certificate is carried in the pack as receivables.borrowing_base_certificate. The recurring certificate message is standardised in borrowing-base-certificate.schema.json (v0.1.0). The validator enforces the certificate's arithmetic: eligible ≤ gross, and availability ≤ eligible × advance rate. Trade finance is also continuous: the facility is underwritten once, then per-transaction documents (trade_finance.shipping_documents) recur over its life.

Profile reference

This section lists every profile in full: the required evidence, with catalogue labels. The listing is generated from requirement-profiles.v0.json + the field catalogue.

baseline-v0

applies to: — (fallback) · mode one_shot · status v0

term-loan-v0

applies to: term_loan revolving_credit_facility overdraft · mode one_shot · status v0

asset-finance-v0

applies to: asset_finance_hp asset_finance_lease sale_and_leaseback · mode one_shot · status v0

invoice-finance-v0

applies to: invoice_discounting factoring · mode continuous · status draft

development-finance-v0

applies to: development_finance · mode one_shot · status draft

mezzanine-v0

applies to: mezzanine_subordinated · mode one_shot · status draft

bridging-v0

applies to: bridging · mode one_shot · status draft

trade-finance-v0

applies to: trade_finance · mode continuous · status draft

merchant-cash-advance-v0

applies to: merchant_cash_advance · mode one_shot · status draft

asset-based-lending-v0

applies to: asset_based_lending · mode continuous · status

inventory-finance-v0

applies to: inventory_finance · mode continuous · status

Terminology & conformance

pack

A single JSON document conforming to the schema: one funding case at a point in time.

field

A named fact inside a section: { value, provenance }.

provenance

The record of how a fact entered the pack. See Provenance.

readiness

The producer's claim that the pack is ready to submit. The validator checks that this claim is coherent.

producer

A system that assembles and emits packs (e.g. a broker platform or origination agent).

consumer

A system that receives packs (typically a funder) and applies its own gates.

Conformance

• A conforming pack validates against the JSON Schema, the catalogue (membership, tag/provenance compatibility, source matching), and the readiness rules. The reference validator implements all three: schema/validate.py.
• A conforming producer emits conforming packs and never fabricates a fact. A value the producer did not establish MUST be emitted as not_collected.
• Accept means parse and process as a valid pack. It never obliges a funder to approve or fund. A conforming consumer MUST accept any pack whose schema_version shares its major version, and SHOULD apply its own freshness policy over provenance.date.

Versioning

The standard is versioned on two semver axes: schema_version (pack shape + rules) and catalogue_version (the field catalogue). This release carries schema 0.5.0 and catalogue 0.15.0. Both versions are REQUIRED inside every pack. Breaking changes are major-version only. Changelog:

• catalogue 0.15.0 / vectors 0.9.0 — development finance monitoring: certified work in place, cost to complete, drawn to date, programme variance (signed — a scheme running early must not read as late) and cost variance. A development facility draws down against the monitoring surveyor's certificate, which is the same event as a proof of delivery, so it reuses the existing evidence model.
• catalogue 0.14.0 / reference-data 0.8.0 — card receipts (0/6 → 6/12 verified): takings measured at the acquirer, a derived average ticket, and the refund and chargeback rate — the card-trade analogue of dilution, which the standard did not ask for anywhere before. Pending settlements are proof of forward receipt, and the payer is the acquirer rather than a debtor who can dispute. Plus an outstanding-charges count from the Companies House charges register.
• catalogue 0.13.0 / profiles 0.7.0 — construction: certified payment applications and retentions. Two assets of two different archetypes — a certified application proves performance, while retention is money contractually due later, conditional on practical completion and then the defects period. Recording retention as certain money would overstate the asset.
• catalogue 0.12.0 / profiles 0.6.0 — industry verticals, modelled as overlays. Recruitment invoice finance is ordinary invoice discounting where the borrower is a staffing agency: the facility does not change, what changes is what can be proven. A new the_ask.performance_evidence_basis selects the overlay; haulage was retro-fitted the same way. Also: a field may now name more than one source, because dilution and debtor days are the same fact whether a transport system or a staffing system measured them.
• vectors 0.5.0 — conformance vectors now carry error_code, the stable machine identifier to assert on. Message prose is explicitly not contractual: an implementer in another language could never match English text, and rewording a message broke consumers. Published alongside a property suite — six invariants a conforming validator must satisfy over a generated document space, not a finite example list.
• catalogue 0.11.0 / code-lists 0.7.0 — inventory as an asset class, and the systems that move the goods: a 14-field stock section, four proof-of-delivery counterparts in receivables, asset-based-lending and inventory-finance profiles, and an inventory line on the borrowing-base certificate. Before this the entire risk basis of invoice finance was self-declared or a PDF.
• catalogue 0.9.0 / profiles 0.4.0 — sharia checklists completed: every named structure carries its evidence checklist (partnership, agency and forward structures included); only other has no fixed checklist. Status labels rewritten in plain words.
• catalogue 0.8.0 / code-lists 0.5.0 / profiles 0.3.0 — opt-in sharia-compliant structuring: the finance_basis switch, the sharia_compliance section, the sector gate, per-structure evidence via the profiles overlay, and the S1/S2/S3 ladder. Additive; conventional packs unchanged.
• schema 0.4.0 / catalogue 0.7.0 — the audit fix pass (fixes found by an audit): datatype enforcement (ratio = a 0–1 decimal fraction — 0.7, never 70; coverage multiples use decimal); the generated strict schema; canonical instance grammar (no leading zeros in instance numbers, and the bare unnumbered instance must come first); catalogue_version required; disposition hardened (v0.2.0); artifact cross-validation in CI.
• catalogue 0.6.0 / profiles 0.2.0 — the exhaustive-depth pass (every section filled out in full detail): 13 sections, 148 fields; new trade_finance + card_receipts sections; every section deepened with enough detail to implement against (VAT / CCJ-register / title-number verification, exit strategy + evidence, borrowing-base certificate, HMRC arrears, group structure, planning & build evidence); profiles for bridging, trade finance and merchant cash advance — only other remains unprofiled.
• schema 0.3.0 / catalogue 0.5.0 — repeating groups (party/asset sections may appear as guarantor:2, guarantor:3, … instances with per-instance provenance; the change is additive and previously-valid packs stay valid); the disposition message (the funder's machine-readable response + decline-reason codes); the normative Pack Summary sheet.
• catalogue 0.4.0 — debt-spectrum coverage (Std-10): the facility_type taxonomy (15 products), per-product requirement profiles (requirement-profiles.v0.json, incl. continuous readiness mode for receivables facilities), and three new evidence sections — receivables, capital_structure, development (11 sections, 71 fields).
• catalogue 0.3.0 — the data-dictionary upgrade: datatype + definition on every field; code-list bindings; the code-lists and reference-data artifacts; the x_ extension namespace (schema_version unchanged at 0.2.0 — additive).
• 0.2.0 — provenance aligned with producer output (date/label); structured values; attestation object; entity gate; baseline requirement profile; guarantor / lei / dscr in the catalogue. Hardened after an adversarial review (2026-07-15).
• 0.1.0 — initial extraction from the AskVouch dealpack producer.

Pack structure

A pack is a single JSON object with six top-level members:

The field object

{ "value": string | number | boolean | null | array | object,
  "provenance": { "kind": "verified" | "self-declared" | "document" | "not_collected", ... } }

A value of null means not provided. The field catalogue governs which section_id.field_id pairs are legal. The reference validator enforces this rule; the JSON Schema document does not. This split is deliberate: the catalogue can be versioned on its own.

Producer identity (v0.5)

The producer block records who assembled the pack. It is optional and recommended. In v0 provenance is the producer's recorded claim rather than a proof a consumer can check independently, so trusting a pack means trusting its producer. A consumer needs to know whose claim it is.

"producer": {
  "name": "Example Origination Ltd",
  "role": "origination platform",
  "fca_status": "appointed_representative",   // authorised | appointed_representative
                                              //   | unregulated | not_applicable | not_stated
  "fca_frn": "000000",                        // checkable on the FCA Register
  "principal_name": "Example Principal Ltd",  // required for an appointed representative
  "contact": "[email protected]" }

The validator enforces three rules when the block is present. The block must name the producer. An appointed representative must name its principal, because FSMA s.39 places regulatory responsibility on the principal. An authorised producer or appointed representative should carry its Firm Reference Number, so a consumer can check the FCA Register entry.

Repeating groups (v0.3)

A repeating group is a section that may appear as multiple instances in one pack. The catalogue marks three sections repeatable: true: people, guarantor, and security_assets. Further instances carry the suffix :2, :3, … The first instance uses the bare id:

"sections": {
  "guarantor":   { "guarantor_name": { "value": "A. Director", ... } },
  "guarantor:2": { "guarantor_name": { "value": "B. Director", ... } }
}

Each instance carries its own fields with their own per-fact provenance. Example: a two-guarantor deal where one guarantor's ID is verified and the other's is outstanding is representable. readiness.missing entries may be instance-qualified (guarantor:2.guarantor_id). Instances of non-repeatable sections are rejected by the reference validator. Instance ids follow strict rules: no leading-zero suffixes (guarantor:02 is rejected), an instance requires the bare first instance, and missing may only cite instances present in the pack.

Minimal skeleton

{
  "standard": "lending-deal-package-readiness",
  "schema_version": "0.5.0",
  "catalogue_version": "0.15.0",
  "entity": { "legal_form": "ltd", "jurisdiction": "GB" },
  "sections": { "the_ask": { "amount": { "value": 75000,
      "provenance": { "kind": "self-declared" } } } },
  "readiness": { "status": "gaps-remaining", "attested": false,
      "conformance_level": "L1-declared",
      "missing": ["business_identity.company_name", "..."] }
}

Namespaces

The standard defines three namespaces that keep it extensible without forking. Insurance data standards already use this pattern:

• Core — every field in the catalogue. Portable across producers and consumers.
• Jurisdiction — profiles will localise sources and requirements without changing the shape (UK-first today; a US profile swaps companies_house for state registries). Planned, not yet specified.
• Extension — a producer MAY carry additional fields prefixed x_ (e.g. x_internal_score). Extension fields must still be {value, provenance}-shaped; the validator accepts them, but they do not count towards catalogue membership or conformance scoring. Un-prefixed unknown fields are rejected.

Disposition messages

disposition.schema.json · v0.2.0 · companion to the pack standard

The framework's thesis is "the agent proposes; provenance and deterministic gates dispose." A disposition is the funder's response to a submitted pack. The pack standardises the proposal; the disposition standardises the funder's response. Every funder responds in the same shape. An information request can drive the producer's chase engine directly, with no retyping from an email.

The message

{ "standard": "lending-deal-package-readiness/disposition",
  "disposition_version": "0.2.0",
  "pack_ref": "sha256:…",              // which pack version is being disposed
  "status": "info_requested",           // received | in_review | info_requested
                                        //   | declined | offer_issued
  "info_requested": { "field_ids": ["financials.statutory_accounts",
                                    "guarantor:2.guarantor_id"] },
  "actor": "gate:baseline-checks",      // or a named underwriter + capacity
  "timestamp": "2026-07-18T09:00:00Z" }

• pack_ref — pack identity. A pack MUST be transmitted in its canonical serialization (keys sorted, compact separators, UTF-8 — validate.canonical_json). pack_ref is sha256: + the hex SHA-256 of those bytes (validate.pack_ref). Because transmission is canonical, a hash of the received bytes and an independently computed hash agree. A re-serialized pack is a different identity.
• info_requested.field_ids — catalogue field ids, instance-qualified where needed; REQUIRED when status is info_requested. Each id becomes a chase item mechanically.
• declined.reason_code — REQUIRED when status is declined; codes from code list decline_reason so a decline is actionable and auditable rather than free text.
• actor — a system name when a deterministic gate disposed; a named underwriter + capacity when a human did. The value records which kind of actor disposed.
• offer_issued carries no terms. Pricing and terms are a non-goal; they travel in the funder's own documents.

Rules

• A disposition references exactly one pack version (pack_ref).
• Statuses define no mandatory workflow order. Any order is legal; consumers MUST NOT assume a fixed sequence. continuous-mode facilities expect repeated dispositions over the facility's life.
• field_ids MUST reference catalogue fields — enforced by validate.validate_disposition(msg, catalogue).
• A disposition is the funder's operational statement, not a regulatory decision notice; where regulated-lending notice obligations apply they are the funder's own and travel separately.
• Transport is deliberately out of scope for v0. Packs, summaries, certificates and dispositions are transport-neutral documents; how they travel (endpoints, webhooks, auth) is between the parties. Transport neutrality does not waive security obligations: parties MUST agree a secure channel before exchanging packs that carry personal data. A minimal HTTP binding is a named roadmap item.

The exchange (sequence)

Source: exchange.mmd · the certificate message: borrowing-base-certificate.schema.json (arithmetic enforced: eligible ≤ gross; availability ≤ eligible × advance rate).

Sharia-compliant structuring

opt-in overlay · catalogue v0.15.0 · spec: spec/sharia-structuring.md

The framework supports sharia-compliant deals through one field: the_ask.finance_basis. The default is conventional: the deal is checked like any other. Setting it to sharia_compliant adds a further set of sharia compliance checks and required evidence, for that deal only. These additions are called the overlay, and this page lists them. Both kinds of deal use the same pack format and can run side by side. A funder can require the setting or ignore it. The setting adds checks and never removes any, so there is no separate Islamic version of the standard.

The checks focus on the structure of the deal, because that is what sharia compliance depends on. Example: in a cost-plus sale (murabaha), the funder must buy the asset first and then sell it to the customer. If the funder pays the money straight to the customer instead, the deal is an interest loan with a different name, and a certificate cannot fix that. The standard therefore records two things: evidence of how the deal was built, and who certified the product. The standard does not judge religious questions. Scholars disagree on some structures. The pack records the structure used and the board that approved it; the funder's own board decides whether to accept it.

The five layers

1. Sector gate — deterministic. A pack whose verified SIC codes match the sharia_excluded_sic prefixes (alcohol, gambling, tobacco, weapons, interest-based finance, …) cannot carry the switch. This is a minimum check, not the whole test.
2. Per-structure evidence. The chosen sharia_structure selects its evidence set (below) — the way facility_type selects a requirement profile.
3. The sequence rule. ownership_transfer_date must not follow sale_contract_date: the funder must own before it sells. The validator checks that the recorded dates are in that order.
4. Prohibition terms as evidence. The late-payment-charity clause (late amounts route to charity, never to income) is required for any sharia-compliant readiness claim.
5. Certification of the template, conformity of the deal. Boards certify the product template; the pack records who certified, the certificate and its review date — while layers 1–4 evidence that this deal actually followed it. A readiness claim needs both the structure evidence (layers 1-4) and the certification record (layer 5); neither substitutes for the other.

Structure evidence requirements

Base overlay (every sharia-compliant deal): the structure itself + the late-payment-charity clause — on top of whichever facility profile applies. Generated from requirement-profiles.v0.json.

The S-ladder

Claimed via sharia_compliance.claimed_level; the validator checks the claim against the evidence, the same way it checks L1/L2/L3. Worked example: example-pack.sharia.json (murabaha at S2 — disclosed cost + markup, dated ownership-before-sale, honest gaps), plus sector-gate and sequence negatives in the conformance vectors.

Lifecycle

the process view — pack readiness states + disposition states · source: docs/deal-schema/lifecycle.mmd

This page describes the lifecycle of a case from first collection to funder disposition. The left lane shows the producer's ordered readiness states. The validator's deterministic gates guard each transition. The right lane shows the funder's disposition states. Two loops close the system. The first loop is the information request, which feeds the chase engine automatically. The second loop is monitoring: continuous-mode facilities cycle through recurring certificates for the life of the facility.

• Every producer transition is validator-gated. L2 requires verified facts and no self-declared verify-fields. The oven-ready state requires the profile's required fields and the entity gate. L3 requires the attestation with substance.
• The disposition sequence is not fixed. A funder may go straight from RECEIVED to DECLINED. Consumers MUST NOT assume the full sequence (spec/disposition.md).
• The two loops complete the lifecycle. An info-request closes the gathering loop by feeding the chase engine automatically. The monitoring cycle is the process-view form of readiness_mode: continuous. The recurring borrowing-base certificate is its evidence artifact.

The Pack Summary sheet

normative content · advisory layout · companion to the pack standard

The Pack Summary is the one-page human rendering of the machine-readable pack. The pack itself is the contract. The summary is the sheet that circulates: a broker forwards it, and an underwriter attaches it to a credit paper.

Required content

1. Identity — applicant name, company number, legal form, jurisdiction; the entity-gate statement when the pack claims readiness (corporate-only, v0).
2. The ask — amount, purpose, facility type (label, not code).
3. The verdict — readiness status, conformance level (L1/L2/L3), and the requirement profile that was applied.
4. The provenance mix — per section, each repeatable instance shown separately: counts of verified / self-declared / document-backed / not-collected facts. The mix is the sheet's core content. The reader sees how much of the pack is verified before reading any value.
5. The missing list — every readiness.missing entry with its field label, instance-qualified where applicable.
6. Attestation — attested or not; when attested: who (name + capacity) and when.
7. Standard + versions — standard name, schema_version, catalogue_version, and the pack content hash where computed (the natural pack_ref for dispositions).
8. The reliance disclaimer — an attestation does not move legal responsibility to a receiving firm, and does not remove that firm's own duty to check; screening results are for information only.

A Pack Summary MUST NOT add facts that are not in the pack, rank or recommend lenders, or state provenance more strongly than the pack records it.

Layout (advisory)

The advisory layout is a single page. The verdict and provenance mix sit at the top of the page. The missing list follows. The attestation and the disclaimer sit at the foot. Producers may build a reference rendering. Conformance applies to the sheet's content, not to its styling.

Reference rendering

This is the sheet rendered from example-pack.ready.json. Every value comes from the pack. Nothing is added.

The same renderer applied to a pack with outstanding items (example-pack.mid.json):

Glossary

This glossary defines the standard's concepts for readers new to it. Per-field definitions live in the field catalogue (every field carries a datatype and a definition); this page defines the concepts that the fields build on.

Entity model

explanatory, not normative: the JSON pack instance and the reference validator remain normative · source: docs/deal-schema/data-model.mmd

This page describes every object the standard defines and how the objects relate. The diagram groups the objects into three clusters. The actors and messages cluster (left) covers who builds and sends the pack and who decides on it. The pack anatomy cluster (centre) covers what a pack is made of. The governing artifacts cluster (right) covers the versioned files that say what a pack may contain and when it is ready.

How to read it

• The pack anatomy (centre): a pack carries its two version stamps (both required), one applicant entity (the gate), one readiness verdict (with optional attestation), and one-or-more section instances. Each instance carries fields. Every field carries exactly one provenance.
• The governing artifacts (right) are versioned files, not runtime objects. The catalogue says which sections/fields may exist (and their tag, datatype, code list, source). The facility type selects the requirement profile. The profile determines what missing[] means for this pack.
• The actor loop (left) shows the framework's central idea as data. The producer assembles the pack. The funder consumes the pack and issues a disposition that references the exact pack version it decided on.

Mermaid source (renders in any mermaid tool): docs/deal-schema/data-model.mmd. A logical database model is deliberately out of scope (spec non-goals). This page explains the objects. It does not prescribe storage.

Provenance

Provenance records how each fact entered the pack. Provenance is the standard's central object. A consumer reasons about a pack one fact at a time.

Tag ↔ provenance compatibility

Each catalogue field carries a tag describing how the fact is expected to enter the pack. The validator enforces compatibility:

A verified fact's source MUST additionally match the source the catalogue names for that field. Example: company_name verifies against companies_house, not an arbitrary string.

Freshness

Freshness is a consumer-side rule. Validation deliberately excludes fact age, so a pack never fails solely because time has passed. Each consumer sets its own rule for how fresh a fact must be, using provenance.date. The reference implementation provides stale_facts(pack, as_of, max_age_days), which returns the verified facts older than the given age. expires_at allows a producer to pre-declare an expiry.

Trust boundary (v0 limitation)

In v0, provenance is an honest claim by the producer, not a proof anyone else can check. Trusting a pack therefore means trusting its producer. Verifiable evidence anchors (signed attestations, hashable source responses, digital company identity) are planned to remove this limitation. Until then a consumer SHOULD treat a pack as strong preliminary evidence and re-check the facts that matter most.

Readiness & conformance levels

The readiness object is the producer's claim. The validator checks that the claim is coherent with the pack's contents. The reference validator enforces all rules below.

status / missing

• status is oven-ready or gaps-remaining.
• missing lists the required fields not provided (value null or absent), per the catalogue's baseline requirement profile (required_fields, profile baseline-v0). A required gap MUST appear in missing. Silent omission is not permitted.
• oven-ready ⇒ missing == []. gaps-remaining ⇒ missing non-empty. Optional fields MAY be absent at oven-ready.

Conformance levels

Attestation

attested: true requires a non-empty declarations.truth_statement AND an attestation object: { attested_by, attested_at, statement_ref? }.

Entity gate

entity.legal_form may describe any applicant (ltd | llp | plc | partnership | sole_trader | other). A readiness claim (oven-ready, attested, or L2+) requires a corporate form (ltd/llp/plc). entity.legal_form must agree with business_identity.legal_form. Rationale: sole-trader and small-partnership lending can be a regulated credit agreement (RAO art 60B, subject to the art 60C exemptions; partnerships via art 60L). v0 does not cover regulated agreements. See Regulatory notes.

Field catalogue — the data dictionary

catalogue_version 0.15.0 · 15 sections · 220 fields · baseline profile baseline-v0 (per-product profiles: Lending coverage)

The field catalogue is the data dictionary for the deal package. Every field carries a datatype and a definition. The definition appears in the muted row beneath each entry. Datatype vocabulary: string · text · monetary_amount (GBP) · integer · decimal · ratio · date (ISO 8601) · boolean · enum:<code-list> · document_ref · list_string · url. ● marks the baseline required fields. The baseline is the minimum a pack must provide (value not null) to be oven-ready. The baseline fields are: business_identity.company_name, business_identity.company_number, business_identity.legal_form, financials.statutory_accounts, banking.bank_statements, the_ask.amount, the_ask.purpose, declarations.truth_statement.

business_identity — Business identity

financials — Financials

banking — Banking

security_assets — Security & assets

people — People

guarantor — Guarantor & personal financials

the_ask — The ask

declarations — Declarations

receivables — Receivables & debtor book

inventory — Inventory & stock

capital_structure — Capital structure & subordination

development — Development finance

trade_finance — Trade finance

card_receipts — Card receipts (merchant cash advance)

sharia_compliance — Sharia-compliant structuring

Code lists

code_lists_version 0.8.0 · 23 lists · code-lists.v0.json

A code list is a versioned list of allowed codes, published as part of the standard in its own right. A catalogue field bound to a list (its datatype reads enum:<list>) must carry one of the listed codes as its value. The reference validator enforces this rule. Pack-level enumerations (provenance_kind, readiness_status, conformance_level) are also published here. This gives consumers one place to resolve every code.

legal_form

Legal form of the applicant entity.

provenance_kind

How a fact entered the pack.

field_tag

How a catalogue field is expected to be established.

readiness_status

The pack-level readiness verdict.

conformance_level

Evidence level the pack conforms to.

data_class

Data-protection classification of a field.

guarantee_type

Type of personal guarantee offered.

security_type

Security offered against the facility.

use_of_funds

Purpose category for the requested facility (the facility-purpose classification — authored v0, refine with funder input).

verification_source

Named sources a verified fact may cite — see reference-data.v0.json for registry detail.

disposition_status

Funder response states for a submitted pack (disposition.schema.json). The disposition message is how 'the funder disposes' becomes machine-readable.

decline_reason

Structured decline reasons — so a decline is actionable by the producer (and its chase engine) rather than free text.

facility_type

The debt product/instrument requested — the product taxonomy (distinct from use_of_funds, which classifies purpose).

repayment_profile

The repayment shape sought for the facility.

exit_strategy

How an exit-led facility (bridging, development) will be repaid at term.

property_tenure

Tenure of charged property.

trade_direction

Direction of the funded trade flows.

finance_basis

Per-deal financing basis. Absent = conventional; sharia_compliant activates the sharia overlay (sector gate, structure evidence, S-ladder).

sharia_structure

Islamic financing structures. The standard evidences the chosen structure's checkable requirements; it does not rule on the structures themselves — certification does.

sharia_level

Sharia conformance ladder — mirrors L1/L2/L3. Coherence enforced by the reference validator.

sharia_excluded_sic

Deterministic sector gate: UK SIC 2007 prefixes excluded for sharia-compliant deals — a pack whose VERIFIED sic_codes match any prefix cannot carry finance_basis sharia_compliant. A floor, not a ceiling: codes catch what codes can catch; certification review covers the rest.

stock_valuation_basis

performance_evidence_basis

Reference data

reference_data_version 0.8.0 · 17 registries · reference-data.v0.json

This page lists the external registries a verified fact may cite as its source. Each entry states what the registry verifies, its identifier format, and its access terms. A verified fact's source must be one of these registries. The source must also match the catalogue's named source for the field. Identifier formats are provisional until we have checked each source's terms.

companies_house — Companies House

fca_register — FCA Financial Services Register

gleif — GLEIF — Global LEI Index

sic_codes — UK SIC 2007

disqualified_directors_register — Register of disqualified directors

sanctions_screen — Sanctions & PEP screening

open_banking — UK Open Banking (account information)

land_registry — HM Land Registry (planned adapter — cited by security_assets.title_number)

hmrc_vat — HMRC VAT registration checker

registry_trust — Register of Judgments, Orders and Fines

structuring_need_map — Deterministic product-structure map

accounting_api — Accounting system (Open Accounting)

wms_api — Inventory / warehouse management system

tms_api — Transport / logistics management system

staffing_api — Recruitment pay-and-bill / staffing system

construction_pm_api — Construction project / contract administration system

psp_api — Card acquirer / payment service provider

JSON Schema

https://askvouch.com/schemas/deal-package-readiness/v0.5.0/deal-package.schema.json · JSON Schema 2020-12

This is the full, normative schema document. Validation is split between the schema and the reference validator by design. The schema checks the pack's shape: the envelope, field objects, provenance variants, and the readiness object. The reference validator enforces the rest — catalogue membership, tag compatibility, and the readiness rules. This split allows the catalogue to version independently of the schema.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://askvouch.com/schemas/deal-package-readiness/v0.5.0/deal-package.schema.json",
  "title": "Lending Deal-Package Readiness — pack instance",
  "description": "Validates a FILLED deal package: every fact carries a value + provenance, and the pack carries a readiness verdict. Provenance and readiness are first-class — a publishable layer no open lending standard currently provides. WHICH fields may appear is governed by field-catalogue (see catalogue_version). NOTE: the $id namespace is provisional (askvouch.com, owned) pending a neutral home and name clearance.",
  "type": "object",
  "required": [
    "standard",
    "schema_version",
    "catalogue_version",
    "entity",
    "sections",
    "readiness"
  ],
  "properties": {
    "standard": {
      "const": "lending-deal-package-readiness"
    },
    "schema_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$"
    },
    "catalogue_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$"
    },
    "entity": {
      "type": "object",
      "required": [
        "legal_form"
      ],
      "additionalProperties": false,
      "properties": {
        "legal_form": {
          "description": "Broad enum so a pack can DESCRIBE any applicant. The eligibility GATE is a readiness rule (enforced by the reference validator): oven-ready / L2+ / attested packs require a corporate form (ltd/llp/plc). sole_trader and small-partnership lending can be a regulated credit agreement (RAO art 60B, subject to the art 60C exemptions; partnerships via art 60L) — such packs may relate to a regulated credit agreement and implementers carry the corresponding FCA obligations; a dedicated regulated-agreement profile is future work, not covered by v0.",
          "enum": [
            "ltd",
            "llp",
            "plc",
            "partnership",
            "sole_trader",
            "other"
          ]
        },
        "jurisdiction": {
          "type": "string",
          "default": "GB"
        }
      }
    },
    "sections": {
      "type": "object",
      "minProperties": 1,
      "description": "section_id -> { field_id -> field }. Legal section/field ids are governed by the field catalogue — enforced by the reference validator (cross_check_catalogue), not by this schema document. REPEATING GROUPS (v0.3, additive): sections the catalogue marks repeatable:true may appear as further instances suffixed ':2', ':3', … (e.g. 'guarantor', 'guarantor:2') — each instance with its own per-fact provenance. Instances of non-repeatable sections are rejected by the reference validator.",
      "additionalProperties": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/$defs/field"
        }
      }
    },
    "producer": {
      "type": "object",
      "description": "OPTIONAL but RECOMMENDED (v0.5.0): who assembled this pack. In v0 provenance is the producer's recorded claim rather than a proof a consumer can check independently, so trusting a pack means trusting its producer. This block lets a consumer know whose claim it is, and what regulatory status that party holds.",
      "required": [
        "name"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "The legal or trading name of the party that assembled the pack."
        },
        "role": {
          "type": "string",
          "description": "How the producer acted on this case, e.g. 'origination platform', 'broker', 'lender'."
        },
        "fca_status": {
          "description": "The producer's FCA position for the activity carried on in assembling and passing this pack. not_stated is honest; omitting the block entirely says nothing at all.",
          "enum": [
            "authorised",
            "appointed_representative",
            "unregulated",
            "not_applicable",
            "not_stated"
          ]
        },
        "fca_frn": {
          "type": "string",
          "description": "The Firm Reference Number on the FCA Register, where the producer is authorised or an appointed representative. Checkable against the fca_register entry in reference-data."
        },
        "principal_name": {
          "type": "string",
          "description": "Where fca_status is appointed_representative: the principal firm that carries regulatory responsibility (FSMA s.39)."
        },
        "contact": {
          "type": "string",
          "description": "A contact address for questions about this pack."
        }
      }
    },
    "readiness": {
      "$ref": "#/$defs/readiness"
    },
    "signatures": {
      "type": "array",
      "description": "OPTIONAL evidence anchors (v1.0 layer, see spec/evidence-anchors-design.md). Each entry is a DETACHED JWS (RFC 7515) over the RFC 8785 JCS canonical bytes named by `over`: 'pack' = the whole document minus this signatures block; 'attestation' = the attestation tuple bound to the pack's content hash, so an attestation cannot be replayed onto a different pack. The signing algorithm is read from the SIGNED protected header, never from an unprotected field, so an algorithm-substitution attack cannot downgrade a signature. Structure only is checked here; authenticity requires a public key the consumer supplies (schema/evidence.py verify_signatures) — the reference validator never fetches a key. NOT yet required by any conformance level: that is the v1.0 rule change.",
      "maxItems": 16,
      "items": {
        "type": "object",
        "required": [
          "over",
          "protected",
          "signature"
        ],
        "additionalProperties": false,
        "properties": {
          "over": {
            "description": "What the signature covers.",
            "enum": [
              "pack",
              "attestation"
            ]
          },
          "protected": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "base64url (unpadded) JOSE protected header — carries the signed `alg` and `kid`, and optionally `frn` binding the key to the producer's FCA Firm Reference Number."
          },
          "signature": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "base64url (unpadded) signature. ES256 is raw R||S per JOSE, not DER."
          }
        }
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "field": {
      "type": "object",
      "required": [
        "value",
        "provenance"
      ],
      "properties": {
        "value": {
          "type": [
            "string",
            "number",
            "boolean",
            "null",
            "array",
            "object"
          ]
        },
        "provenance": {
          "$ref": "#/$defs/provenance"
        }
      },
      "additionalProperties": false
    },
    "provenance": {
      "description": "How a fact entered the pack, and when it was checked. Aligned with what a producing system (e.g. AskVouch dealpack/assemble.py) actually emits: verified facts carry the check date; document/not_collected may carry a display label.",
      "oneOf": [
        {
          "type": "object",
          "required": [
            "kind",
            "source"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "verified"
            },
            "source": {
              "type": "string"
            },
            "via": {
              "type": "string"
            },
            "date": {
              "type": "string"
            },
            "expires_at": {
              "type": "string"
            },
            "evidence_ref": {
              "type": "string",
              "description": "OPAQUE locator for the stored source response — a storage key, not a fetch instruction. A consumer that chooses to dereference it MUST treat it as untrusted input (allowlist schemes, block SSRF targets, bound size/type/time — see the spec's Security considerations)."
            },
            "evidence_hash": {
              "type": "string",
              "pattern": "^sha256:[0-9a-f]{64}$",
              "description": "OPTIONAL evidence anchor (v1.0 layer, spec/evidence-anchors-design.md §3b): 'sha256:' + hex of the RFC 8785 JCS bytes of the SOURCE'S OWN RESPONSE that established this fact. Lets a consumer re-hash the stored (or re-fetched) response and confirm the producer neither invented nor altered it — the difference between 'we say we checked Companies House' and 'here is the checkable trace'. NOT proof the source was honest, and NOT producer authenticity (that is the pack signature). Computed by schema/evidence.py evidence_hash(); checked by verify_evidence()."
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "self-declared"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "document"
            },
            "checked": {
              "type": "boolean"
            },
            "ref": {
              "type": "string"
            },
            "label": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "not_collected"
            },
            "label": {
              "type": "string"
            }
          }
        }
      ]
    },
    "readiness": {
      "type": "object",
      "required": [
        "status",
        "attested",
        "conformance_level",
        "missing"
      ],
      "additionalProperties": false,
      "properties": {
        "status": {
          "description": "oven-ready REQUIRES missing == [] (enforced by the reference validator). gaps-remaining requires a non-empty missing list.",
          "enum": [
            "oven-ready",
            "gaps-remaining"
          ]
        },
        "attested": {
          "description": "true REQUIRES declarations.truth_statement with a non-empty value AND an attestation object (enforced by the reference validator). An attestation is the packing party's statement — it does NOT transfer legal responsibility to, or discharge the diligence obligations of, a receiving firm.",
          "type": "boolean"
        },
        "attestation": {
          "type": "object",
          "required": [
            "attested_by",
            "attested_at"
          ],
          "additionalProperties": false,
          "properties": {
            "attested_by": {
              "type": "string",
              "description": "Who attests (name + capacity, e.g. 'A. Director, director of the applicant')"
            },
            "attested_at": {
              "type": "string"
            },
            "statement_ref": {
              "type": "string",
              "description": "Reference/hash of the signed truth statement"
            }
          }
        },
        "conformance_level": {
          "description": "L1 = declared-only. L2 = verify-core: no verify-tagged field present in the pack carries a self-declared value (not_collected is permitted — it is the honest absence marker), and at least one verified fact exists. L3 = L2 + attested with attestation object + oven-ready. Enforced by the reference validator.",
          "enum": [
            "L1-declared",
            "L2-verified-core",
            "L3-attested"
          ]
        },
        "missing": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

Reference validator

schema/validate.py · requires jsonschema (hard dependency: validation fails with an explicit error when it is absent)

validate(pack, catalogue) → list[str] returns the pack's conformance errors. An empty list means the pack conforms. The validator applies five check layers:

1. Structure — Draft 2020-12 validation against the schema document.
2. Catalogue — every section.field exists in the catalogue (or is an x_-prefixed extension field, which is permitted and skipped); provenance kind is compatible with the field's tag; a verified fact's source matches the catalogue's named source; an enum field's value is a code in its bound code list; every non-null value matches its catalogue datatype (ratio = 0–1 decimal fraction); instance names follow the canonical grammar (e.g. guarantor:2, not guarantor-2); readiness.missing entries reference real fields; repeatable-section instances (guarantor:2, …) are legal only for sections the catalogue marks repeatable, with integer suffixes from :2.
3. Readiness — the status and the missing list must agree; conformance-level rules apply (L2/L3 forbid self-declared verify-fields and require ≥1 verified fact; L3 requires attested + oven-ready); attestation substance (non-empty truth statement + {attested_by, attested_at}).
4. Entity gate — oven-ready / attested / L2+ require a corporate form; entity vs business_identity legal-form consistency.
5. Requirement profiles — the pack's the_ask.facility_type selects the per-product profile (see Lending coverage); every required field is provided or listed in missing.

Usage

Also exported: validate_disposition(msg, catalogue) (funder dispositions), validate_bbc(msg) (borrowing-base certificates — arithmetic enforced), canonical_json / pack_ref (pack identity hashing), check_artifacts (the standard's own files cross-validated), and run_vectors — runs the 30 published conformance vectors. The vector file therefore cannot drift from the rules.

# self-check: 2 packs (reference AND strict schema) + a disposition
#            + artifact cross-validation + 31 negative cases
cd docs/deal-schema/schema
python validate.py

# programmatic
from validate import validate, stale_facts
errors = validate(pack, catalogue)          # [] == conforming
stale  = stale_facts(pack, "2026-07-17", max_age_days=90)

stale_facts is intentionally outside validate(). Validation is clock-free: the caller supplies "today".

Example packs

This page provides five example packs. All five pass validation. Implementations can use them as test cases as well as documentation. Company identifiers are fictitious.

1 · oven-ready (L3-attested)

All baseline required fields are provided. Identity is verified against Companies House. An attestation is present. missing is empty.

{
  "standard": "lending-deal-package-readiness",
  "schema_version": "0.5.0",
  "catalogue_version": "0.11.0",
  "entity": {
    "legal_form": "ltd",
    "jurisdiction": "GB"
  },
  "producer": {
    "name": "Example Origination Ltd",
    "role": "origination platform",
    "fca_status": "appointed_representative",
    "fca_frn": "000000",
    "principal_name": "Example Principal Ltd",
    "contact": "[email protected]"
  },
  "sections": {
    "business_identity": {
      "company_name": {
        "value": "Example Trading Ltd (synthetic)",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "GET /company/00000000",
          "date": "2026-07-13"
        }
      },
      "company_number": {
        "value": "00000000",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-13"
        }
      },
      "legal_form": {
        "value": "ltd",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-13"
        }
      },
      "company_status": {
        "value": "active",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-13"
        }
      },
      "lei": {
        "value": null,
        "provenance": {
          "kind": "not_collected",
          "label": "LEI (optional for SME packs)"
        }
      },
      "trading_name": {
        "value": "Example Trading",
        "provenance": {
          "kind": "self-declared"
        }
      }
    },
    "financials": {
      "turnover": {
        "value": 1250000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "accounts_overdue": {
        "value": "on time",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-13"
        }
      },
      "statutory_accounts": {
        "value": "accounts-2025.pdf",
        "provenance": {
          "kind": "document",
          "checked": true,
          "ref": "r2://cases/1/statutory/uuid_accounts.pdf"
        }
      }
    },
    "banking": {
      "bank_statements": {
        "value": "6mo-statements.pdf",
        "provenance": {
          "kind": "document",
          "checked": true,
          "ref": "r2://cases/1/bank/uuid_statements.pdf"
        }
      },
      "monthly_credit_turnover": {
        "value": 104000,
        "provenance": {
          "kind": "verified",
          "source": "open_banking",
          "date": "2026-07-12"
        }
      },
      "dscr": {
        "value": 1.6,
        "provenance": {
          "kind": "verified",
          "source": "open_banking",
          "date": "2026-07-12"
        }
      }
    },
    "people": {
      "active_officers": {
        "value": "A. Director, B. Director (2 active officers)",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-13"
        }
      },
      "director_disqualified": {
        "value": "none disqualified",
        "provenance": {
          "kind": "verified",
          "source": "disqualified_directors_register",
          "date": "2026-07-13"
        }
      },
      "sanctions_pep": {
        "value": "clear",
        "provenance": {
          "kind": "verified",
          "source": "sanctions_screen",
          "date": "2026-07-13"
        }
      }
    },
    "guarantor": {
      "guarantee_required": {
        "value": true,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantee_type": {
        "value": "personal",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantee_amount": {
        "value": 50000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantor_name": {
        "value": "A. Director",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "personal_financial_statement": {
        "value": "pfs-413.pdf",
        "provenance": {
          "kind": "document",
          "checked": true
        }
      },
      "guarantor_net_worth": {
        "value": 180000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantor_sanctions_pep": {
        "value": "clear",
        "provenance": {
          "kind": "verified",
          "source": "sanctions_screen",
          "date": "2026-07-13"
        }
      }
    },
    "the_ask": {
      "amount": {
        "value": 75000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "purpose": {
        "value": "new fit-out and equipment",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "candidate_products": {
        "value": "asset finance, secured term loan",
        "provenance": {
          "kind": "verified",
          "source": "structuring_need_map",
          "date": "2026-07-13"
        }
      },
      "term_months": {
        "value": 48,
        "provenance": {
          "kind": "self-declared"
        }
      }
    },
    "declarations": {
      "truth_statement": {
        "value": "I confirm the information in this pack is true and complete — signed 2026-07-13",
        "provenance": {
          "kind": "self-declared"
        }
      }
    }
  },
  "readiness": {
    "status": "oven-ready",
    "attested": true,
    "attestation": {
      "attested_by": "A. Director, director of the applicant",
      "attested_at": "2026-07-13",
      "statement_ref": "sha256:9f2c...truth-statement"
    },
    "conformance_level": "L3-attested",
    "missing": []
  }
}

2 · mid-verification (L2, gaps-remaining)

The pack has a verified core with one required document outstanding. The outstanding document is recorded as not_collected. The same field is listed in missing.

{
  "standard": "lending-deal-package-readiness",
  "schema_version": "0.5.0",
  "catalogue_version": "0.11.0",
  "entity": {
    "legal_form": "ltd",
    "jurisdiction": "GB"
  },
  "sections": {
    "business_identity": {
      "company_name": {
        "value": "Midway Trading Ltd",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-15"
        }
      },
      "company_number": {
        "value": "01234567",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-15"
        }
      },
      "legal_form": {
        "value": "ltd",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "date": "2026-07-15"
        }
      }
    },
    "financials": {
      "statutory_accounts": {
        "value": "accounts-2025.pdf",
        "provenance": {
          "kind": "document",
          "checked": true
        }
      }
    },
    "banking": {
      "bank_statements": {
        "value": null,
        "provenance": {
          "kind": "not_collected",
          "label": "awaiting borrower upload"
        }
      }
    },
    "the_ask": {
      "amount": {
        "value": 120000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "purpose": {
        "value": "premises expansion",
        "provenance": {
          "kind": "self-declared"
        }
      }
    },
    "declarations": {
      "truth_statement": {
        "value": "attested by the applicant",
        "provenance": {
          "kind": "self-declared"
        }
      }
    }
  },
  "readiness": {
    "status": "gaps-remaining",
    "attested": true,
    "attestation": {
      "attested_by": "A. Director, Midway Trading Ltd",
      "attested_at": "2026-07-15"
    },
    "conformance_level": "L2-verified-core",
    "missing": [
      "banking.bank_statements"
    ]
  }
}

3 · early-stage (L1-declared)

Most fields are uncollected. The pack contains only applicant-stated facts. The producer claims nothing it cannot support.

{
  "standard": "lending-deal-package-readiness",
  "schema_version": "0.5.0",
  "catalogue_version": "0.11.0",
  "entity": {
    "legal_form": "ltd",
    "jurisdiction": "GB"
  },
  "sections": {
    "business_identity": {
      "company_name": {
        "value": null,
        "provenance": {
          "kind": "not_collected",
          "label": "awaiting Companies House verification"
        }
      },
      "legal_form": {
        "value": null,
        "provenance": {
          "kind": "not_collected"
        }
      }
    },
    "the_ask": {
      "amount": {
        "value": 40000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "purpose": {
        "value": "working capital",
        "provenance": {
          "kind": "self-declared"
        }
      }
    }
  },
  "readiness": {
    "status": "gaps-remaining",
    "attested": false,
    "conformance_level": "L1-declared",
    "missing": [
      "business_identity.company_name",
      "business_identity.company_number",
      "business_identity.legal_form",
      "financials.statutory_accounts",
      "banking.bank_statements",
      "declarations.truth_statement"
    ]
  }
}

4 · repeating groups (two guarantors)

A second guarantor appears as an instance section (guarantor:2). One guarantor's ID document is checked. The other guarantor's ID document is still outstanding and is listed under its instance in missing.

{
  "standard": "lending-deal-package-readiness",
  "schema_version": "0.5.0",
  "catalogue_version": "0.11.0",
  "entity": {
    "legal_form": "ltd",
    "jurisdiction": "GB"
  },
  "sections": {
    "business_identity": {
      "company_name": {
        "value": "Two Guarantor Trading Ltd",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "api",
          "date": "2026-07-10"
        }
      },
      "company_number": {
        "value": "00000000",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "api",
          "date": "2026-07-10"
        }
      },
      "legal_form": {
        "value": "ltd",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "api",
          "date": "2026-07-10"
        }
      }
    },
    "the_ask": {
      "amount": {
        "value": 250000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "purpose": {
        "value": "Working capital",
        "provenance": {
          "kind": "self-declared"
        }
      }
    },
    "declarations": {
      "truth_statement": {
        "value": "I confirm the information in this pack is true to the best of my knowledge.",
        "provenance": {
          "kind": "self-declared"
        }
      }
    },
    "guarantor": {
      "guarantee_required": {
        "value": true,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantee_type": {
        "value": "personal",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantor_name": {
        "value": "A. Director",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantor_id": {
        "value": "doc-101",
        "provenance": {
          "kind": "document",
          "checked": true
        }
      }
    },
    "guarantor:2": {
      "guarantee_type": {
        "value": "personal",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantor_name": {
        "value": "B. Director",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "guarantor_id": {
        "value": null,
        "provenance": {
          "kind": "not_collected",
          "label": "Photo ID (second guarantor)"
        }
      }
    }
  },
  "readiness": {
    "status": "gaps-remaining",
    "attested": false,
    "conformance_level": "L1-declared",
    "missing": [
      "financials.statutory_accounts",
      "banking.bank_statements",
      "guarantor:2.guarantor_id"
    ]
  }
}

5 · sharia overlay (murabaha, S2-structure-evidenced)

The sharia overlay is active. The structure evidence for a murabaha is present and the recorded dates are in order. Two baseline documents remain outstanding and are listed in missing.

{
  "standard": "lending-deal-package-readiness",
  "schema_version": "0.5.0",
  "catalogue_version": "0.11.0",
  "entity": {
    "legal_form": "ltd",
    "jurisdiction": "GB"
  },
  "sections": {
    "business_identity": {
      "company_name": {
        "value": "Halal Equipment Trading Ltd",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "api",
          "date": "2026-07-10"
        }
      },
      "company_number": {
        "value": "00000000",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "api",
          "date": "2026-07-10"
        }
      },
      "legal_form": {
        "value": "ltd",
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "api",
          "date": "2026-07-10"
        }
      },
      "sic_codes": {
        "value": [
          "70229"
        ],
        "provenance": {
          "kind": "verified",
          "source": "companies_house",
          "via": "api",
          "date": "2026-07-10"
        }
      }
    },
    "the_ask": {
      "amount": {
        "value": 44000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "purpose": {
        "value": "Equipment purchase via murabaha",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "finance_basis": {
        "value": "sharia_compliant",
        "provenance": {
          "kind": "self-declared"
        }
      }
    },
    "declarations": {
      "truth_statement": {
        "value": "I confirm the information in this pack is true to the best of my knowledge.",
        "provenance": {
          "kind": "self-declared"
        }
      }
    },
    "sharia_compliance": {
      "sharia_structure": {
        "value": "murabaha",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "claimed_level": {
        "value": "S2-structure-evidenced",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "late_payment_charity_clause": {
        "value": "doc-201",
        "provenance": {
          "kind": "document",
          "checked": true
        }
      },
      "disclosed_cost": {
        "value": 40000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "disclosed_markup": {
        "value": 4000,
        "provenance": {
          "kind": "self-declared"
        }
      },
      "ownership_transfer_date": {
        "value": "2026-07-01",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "sale_contract_date": {
        "value": "2026-07-03",
        "provenance": {
          "kind": "self-declared"
        }
      },
      "ownership_transfer_evidence": {
        "value": "doc-202",
        "provenance": {
          "kind": "document",
          "checked": true
        }
      },
      "sale_contract": {
        "value": "doc-203",
        "provenance": {
          "kind": "document",
          "checked": true
        }
      }
    }
  },
  "readiness": {
    "status": "gaps-remaining",
    "attested": false,
    "conformance_level": "L1-declared",
    "missing": [
      "financials.statutory_accounts",
      "banking.bank_statements"
    ]
  }
}

Producing packs

This page covers producing a conforming pack. The reference producer is AskVouch's case engine. The engine's internal deal pack is mapped to the standard by dealpack/export_standard.py::to_standard_pack. A CI round-trip test checks that a real assembled pack validates against the published schema, catalogue and validator.

HTTP surface

POST /broker/cases/{id}/pack?format=standard
→ 200 { "ok": true,
        "format": "lending-deal-package-readiness/v0.4.0",
        "pack": { ...conforming pack... } }

POST /broker/cases/{id}/pack            # default: the PDF rendering

Producer requirements

The exporter's mapping rules apply to any producer:

• A producer emits sections as a map {section_id → {field_id → {value, provenance}}}. All internal display metadata is stripped.
• readiness.missing derives from the catalogue's required_fields. A required field whose value is null/absent is a gap.
• The conformance level derives from what the pack actually contains, not from the level a producer claims. L2 requires no self-declared verify-fields and at least one verified fact. L3 also requires a substantive attestation and no required gaps.
• The entity gate applies to every producer: a non-corporate applicant is never oven-ready in v0. The producer emits gaps-remaining and records the gap as business_identity.legal_form in missing[].
• business_identity.legal_form is normalised to the standard enum so that it agrees with entity.legal_form.
• A producer never fabricates: anything not established is not_collected.

Artifacts & downloads

This page serves the standard's machine-readable artifacts directly. The set covers everything an implementer needs to produce, validate, or consume conforming packs without access to any repository. Schemas and code are licensed Apache-2.0. Documentation is licensed CC-BY-4.0 (LICENSE · LICENSE-docs · NOTICE — upstream attributions).

Normative artifacts

Tooling & test vectors

Diagram sources (mermaid)

entity model · lifecycle · exchange sequence · C4 context · architecture

Five-minute start

A=https://askvouch.com/dev/artifacts
for f in field-catalogue.v0.json code-lists.v0.json requirement-profiles.v0.json \
         reference-data.v0.json deal-package.schema.json deal-package.strict.schema.json \
         disposition.schema.json borrowing-base-certificate.schema.json \
         conformance-vectors.v0.json validate.py generate_strict_schema.py; do
  curl -sO $A/$f; done
mkdir -p examples
for f in ready gaps mid multi sharia; do
  curl -so examples/example-pack.$f.json $A/example-pack.$f.json; done

pip install jsonschema
python validate.py   # self-check: examples (both schemas), all published vectors, 31 negatives

Crosswalks

A crosswalk is a concept-level field mapping to an adjacent standard. The framework publishes crosswalks only where licences permit. Crosswalks to member-licensed industry standards are not published. A field-level mapping would inevitably copy their member-licensed identifiers and structure. That route requires their involvement (see Governance). The mappings below are indicative until we verify the source licence terms.

FIBO (Financial Industry Business Ontology)

Source: FIBO (Financial Industry Business Ontology) — EDM Council / OMG, MIT licence
Status: concept-level v0 — FIBO IRIs indicative, verify against fibo published ontologies (Std-1)

SBA Forms 1919 / 413

Source: US Small Business Administration — Form 1919 (Borrower Information, rev. 2023), Form 413 (Personal Financial Statement). US-government works, public domain (17 U.S.C. s.105).
Status: concept-level v0 — SBA line references indicative, verify against current SBA forms (Std-1)

Regulatory notes

This page describes the regulatory duties that implementers of the standard carry. The standard is a data structure. It does not create a lawful basis. It is regulation-aware: it flags legal duties but does not create or satisfy them. None of this is legal advice.

UK regulated-credit perimeter

• Lending to sole traders and small partnerships can be a regulated credit agreement (RAO art 60B, subject to the art 60C exemptions; partnerships via art 60L). v0 excludes regulated agreements. The corporate-only entity gate keeps readiness claims outside that scope; assembling or introducing non-corporate cases remains the implementer's own perimeter analysis.
• Introducing borrowers to lenders is credit broking (RAO art 36A) — an FCA-regulated activity. A firm needs FCA permission, or can act as an Appointed Representative under FSMA s.39. Under that arrangement, a principal firm takes regulatory responsibility for the representative's conduct (SUP 12; PS22/11 oversight duties).

Data protection (UK GDPR)

• Packs carry personal data: director and guarantor identity, personal financials, screening results. Catalogue fields are marked data_class: personal.
• Each party assembling or receiving a pack is a controller in its own right and must establish lawful basis, minimisation, retention, and security independently.
• A DPIA (data protection impact assessment) is likely required for packs that include a guarantor.

Financial crime (MLRs)

• Sanctions/PEP results in a pack are informational. They do not replace the receiving firm's own customer due diligence under MLR 2017. Reliance on another firm's checks requires an explicit regulation-39 arrangement.

Guarantors

• A guarantor is a natural person. Where the underlying agreement is regulated, implementers must meet the Consumer Duty, the CONC guarantor provisions, and the rules on vulnerable customers.
• A guarantee secured on a dwelling can trigger the regulated-mortgage analysis. The guarantor.ila_confirmation field records evidence of independent legal advice.

Participate

This page describes how to take part in the standard. The standard is open: schemas and code are Apache-2.0, documentation is CC-BY-4.0, and every artifact is downloadable from this site. The standard improves when parties other than its authors implement it. The first funder that accepts a pack and returns a disposition proves the standard in practice.

Implementers

Implementers produce packs from their own origination systems or consume them in their own credit checks (gates). The starting points are the artifacts, the reference architecture, and Producing packs. The strict schema and the conformance vectors are built for independent implementation. The maintainers treat ambiguous or wrong spec passages as reportable findings.

Funders

For credit teams states what a funder receives, what it still carries, and how a pilot runs.

Funder credit teams can receive conforming packs: per-fact provenance, a readiness verdict their gates can act on, and structured dispositions in return. The maintainers are shaping requirement profiles with early funders now, privately.

Contact

[email protected] is the contact address. Implementation questions, spec findings, funder conversations, and governance interest all reach the maintainers there. The maintainers intend to hand stewardship to a recognised industry or national standards body (see Governance). Interest in taking part in that process goes to the same address.

Governance, IP & licensing

Stewardship

v0 is stewarded by AskVouch as the reference implementation. The maintainers intend to contribute the protocol, open-source, to a neutral standards home once the standard has committed industry participants. A neutral standards home is a recognised industry or national standards body. Governance is deliberately left open for the industry to shape. Alternatives remain open: a neutral foundation, or an existing standards body sponsoring a lending profile.

Interim charter

The interim governance charter states how decisions are made before stewardship transfers. It covers decision rights, the change-control process, the licences, the conformance position of the reference implementation, the transfer criteria, and the maintainers' conflict of interest. Implementers running a conforming producer or consumer may request a standing seat in the review of normative changes.

Change control and comment windows

• A proposed normative change is published as a draft with a version number and a dated comment window of at least 21 days.
• Comments go to [email protected]. Comments and their disposition are recorded in the changelog entry for the release.
• Every release states whether it is additive or breaking. Breaking changes carry a migration note.
• Requirement profiles follow this process. Profiles shaped with individual funders are published as drafts and go through the same window before they are treated as normative.
• Editorial fixes, security fixes and corrections of factual errors ship immediately and are marked as such.

Patents

Copyright licences alone do not tell an implementer where they stand on patents. The patent non-assertion pledge does. The maintainers pledge not to assert patent claims they own or control against conforming implementations, with a defensive-suspension condition, and will require any successor steward to maintain a pledge at least as permissive. The maintainers hold no patents or applications covering the standard's normative artifacts.

Licences

Conflict of interest

The maintainers operate a commercial product that consumes this standard. Two safeguards apply. The artifacts are licensed so that a competitor can implement them fully without permission. No normative change may require a feature that only the reference implementation can provide. The reference implementation runs the same published conformance vectors as any other implementation.

IP process

Content is drawn only from public-domain / open sources (SBA forms, FIBO, UK Open Banking). We consult member-licensed industry standards only as checklists of concepts to cover. We copy no schema file, field dictionary or datapoint identifier. We keep a per-concept provenance log and a blocking licence-verification log (ip-process.md).

Contributing

CONTRIBUTING.md defines the contribution requirements. All changes must pass the reference validator and the producer round-trip. New fields need catalogue entries and a requirement-profile decision. Borrowed fields also need a provenance-log row and a NOTICE entry.