Schema reference, draft 0.1

Every type of OFAP draft 0.1, generated from schema.ts through schema.json. The sections follow schema.ts. The rules in the descriptions use the RFC 2119 keywords.

1.Identity of the extension

ConformanceLevel

Conformance level that a distributor declares.

• 1 Inform: get_distributor, list_products, get_documents
• 2 Quote: level 1, plus get_question_set and quote
• 3 Subscribe: level 2, plus submit_application or conclude
• 4 Service: level 3, plus get_agreement and amend_agreement

A server that declares a level MUST implement every tool of that level and of the levels below it, except that level 3 needs only one of submit_application and conclude.

Type: one of 1, 2, 3, 4.

InterfaceKind

How a distributor exposes the protocol.

Type: one of tools, conversation.

OfapSettings

Settings object of the extension. A server puts it under capabilities.extensions["org.openfinancialagent/ofap"] in its MCP server/discover response, and under the same key in the extensions field of its PAP poppy.json.

2.Common types

CountryCode

ISO 3166-1 alpha-2 country code, upper case.

Type: string. Pattern: ^[A-Z]{2}$.

CurrencyCode

ISO 4217 currency code.

Type: string. Pattern: ^[A-Z]{3}$.

LanguageTag

BCP 47 language tag, for example fr or es-ES.

Type: string. Pattern: ^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$.

DateString

Calendar date, ISO 8601.

Type: string (date).

DateTimeString

Date and time with offset, ISO 8601.

Type: string (date-time).

Url

Type: string (uri).

Sha256

Lower-case hex SHA-256 digest.

Type: string. Pattern: ^[a-f0-9]{64}$.

Decimal

A decimal number as a string, so that no value is lost to floating point, for example "12.90".

Type: string. Pattern: ^-?[0-9]+(\.[0-9]+)?$.

Money

ProductLine

Product line. Servers SHOULD use a value of KnownProductLine. Other values MUST be lower case with underscores.

Type: string. Pattern: ^[a-z][a-z0-9_]*$.

KnownProductLine

Lines that have, or will have, a profile in OFAP. A sector module adds its own group.

Type: one of pet, home, renters, motor, travel, health, life, funeral, borrower_insurance, professional_liability, general_liability, business_owners_policy, workers_compensation.

3.Distributor (core, level 1)

DistributorRole

Role of a party in the distribution chain. The provider roles are in ProviderRole. A sector module adds its intermediary roles here.

Type: ProviderRole or broker or agent or mga or comparator.

RegisterIdentifierType

Kind of public register identifier. A sector module adds the registers of its sector.

Type: one of orias_number, fca_frn, npn, dgsfp_key, other.

Licence

One entry in a public register that gives the right to distribute a product.

GetDistributorParams

Params of get_distributor. No params.

Type: object.

GetDistributorResult

4.Products (core, level 1)

ProviderRole

Role of the party that carries the risk or provides the money. A sector module adds its provider role, for example a lender.

Type: insurer.

ProviderRef

The party that carries the risk or provides the money.

SubscriptionPath

How a customer can subscribe to a product.

Type: one of conclude, application, handoff.

Product

ProductDetails

Details of the product's sector. One member per sector module.

Type: InsuranceProductDetails.

ListProductsParams

ListProductsResult

5.Documents (core, level 1)

DocumentType

Kind of document. A sector module adds the documents that the law of its sector asks for.

Type: one of pre_contract_information, terms_of_business, other, ipid, general_conditions, special_conditions, demands_and_needs, proof_of_insurance.

FinancialDocument

GetDocumentsParams

Params of get_documents. Give exactly one of the three references.

Variant 1

Variant 2

Variant 3

GetDocumentsResult

6.Question sets (core, level 2)

CollectedBy

Who collects the value of a question.

• agent: the agent MAY ask and send the value.
• distributor_page: the value MUST NOT pass through the agent. The customer gives it on the distributor's own page. Use it for identity numbers, bank account and card numbers, tax numbers, health details and passwords.

Type: one of agent, distributor_page.

AnswersSchema

A JSON Schema (2020-12) object that describes the answers. Each property is one question. OFAP adds these keywords to each property:

• x-collected-by: a CollectedBy value. Default agent.
• x-profile-key: the key of the matching question in the line profile, when the question is part of the common core.
• x-ask: a short question the agent can ask the customer, in plain words.

QuestionSet

GetQuestionSetParams

GetQuestionSetResult

QuestionSetRef

Answers

Answers keyed by property name in answers_schema.

Type: map of any.

7.Quote (core, level 2)

QuoteParams

Params of quote.

The agent MAY send partial answers. The server then returns needs_input with the missing fields, and the agent calls quote again with more answers. This one loop replaces the multi-step flow tools (action, stateUpdates, sessionId) that most servers use. Some servers already work this way.

To read a quote that is still in progress, send only quote_request_id.

Variant 1

Variant 2

Offer

One priced offer. A distributor can return several offers: one per tier, per provider, or per duration.

Pricing

Price in the form of the offer's sector. One member per sector module.

Type: InsurancePricing.

QuoteResult

status: complete

status: needs_input

status: in_progress

NoOffer

Why no offer is possible.

FieldIssue

8.Sector modules

Sector

Sector modules of this draft. Draft 0.1 defines one module: insurance (section 9).

The core is the same for every sector. A sector module adds what the law of its sector asks for. A module MUST define:

• its value in Sector, and its group of lines in KnownProductLine;
• one member of ProductDetails, Pricing and NeedsAssessment, each with a sector field that holds the module's value;
• its values in ProviderRole, DistributorRole, RegisterIdentifierType, DocumentType, PartyRole and AmendmentChange, when the sector needs them;
• which of its documents are required_before_commitment;
• its line profiles in profiles.ts, and checks for the rules of its sector that a JSON Schema cannot express.

A module MUST NOT change a core type or a core rule. The tools, the quote loop, the declaration, the PAP operations and the evidence record stay the same for every sector.

A server declares the modules it implements in OfapSettings.sectors. An agent MUST NOT show a product, an offer or an agreement of a sector it does not implement as if it were of a known sector.

Candidate modules for a later draft:

• credit: SECCI and ESIS, creditworthiness (CCD Art. 18, MCD Art. 18), APR and total cost of credit;
• investment: KID (PRIIPs), suitability or appropriateness (MiFID II Art. 25), fees and risk indicator.

Type: insurance.

9.Insurance module

PremiumPeriod

Type: one of month, quarter, half_year, year, single.

Premium

CoverLimit

CoverSummary

ProductOption

An option the customer can add (optional cover, extra service).

InsuranceProductDetails

InsurancePricing

InsuranceNeedsAssessment

Demands and needs, recorded before the contract is concluded (IDD Art. 20(1)).

10.Parties, needs and consent (core)

PartyRole

Role of a party in the agreement. A sector module adds the roles of its sector.

Type: one of subscriber, payer, insured, beneficiary.

Party

A person or organisation in the agreement. Data in a party MUST be limited to what the product needs. Identity numbers MUST NOT be here (see CollectedBy).

NeedsAssessment

Needs assessment that the law of the sector asks for. One member per sector module.

Type: InsuranceNeedsAssessment.

ContactConsent

The customer's choice about later contact.

DeliveredDocument

Declaration

The answers the customer commits to.

11.PAP operations with financial terms (levels 3 and 4)

OperationState

Type: one of proposed, in_progress, succeeded, failed, cancelled, expired.

Operation<(ApplicationTerms|AmendmentTerms)>

A PAP operation. This mirrors the PAP operations extension (version 1). PAP is the authority for every field here except terms and ofap_progress. When the two differ, PAP wins.

An MCP tool returns it in structuredContent.operation. The agent confirms it at the PAP operations endpoint, never through an OFAP tool.

Operation<AmendmentTerms>

A PAP operation. This mirrors the PAP operations extension (version 1). PAP is the authority for every field here except terms and ofap_progress. When the two differ, PAP wins.

An MCP tool returns it in structuredContent.operation. The agent confirms it at the PAP operations endpoint, never through an OFAP tool.

Operation<ApplicationTerms>

A PAP operation. This mirrors the PAP operations extension (version 1). PAP is the authority for every field here except terms and ofap_progress. When the two differ, PAP wins.

An MCP tool returns it in structuredContent.operation. The agent confirms it at the PAP operations endpoint, never through an OFAP tool.

OfapProgress

ApplicationTerms

Terms of an application or a conclusion. Every field the law needs as evidence is here, so that a confirmed revision records exactly what the customer accepted.

SubmitApplicationParams

SubmitApplicationResult

When the operation succeeds, result.data holds an ApplicationOutcome.

ApplicationOutcome

ConcludeParams

Type: SubmitApplicationParams.

ConcludeResult

Result of conclude. The operation MUST have user_approval_required: true. When it succeeds, result.data holds a ConcludeOutcome.

ConcludeOutcome

12.Evidence (core)

EvidenceRecord

What the distributor keeps when an operation succeeds. It links the exact revision the customer accepted to the documents, the declaration, the needs assessment and the consent. The distributor MUST keep it for the period the law requires.

A PAP confirmation proves that an agent stated the customer approved a revision. It does not prove that the customer saw the terms. This record adds what was delivered and what was declared. It still does not prove that the customer read the documents.

13.Agreements (core, level 4)

AgreementStatus

Type: one of pending, active, suspended, lapsed, cancelled, closed, expired.

Agreement

An agreement in force. In the insurance module, a policy.

Subject

GetAgreementParams

Requires a signed-in PAP session with read scope.

GetAgreementResult

AmendmentChange

One change to an agreement. A sector module adds the changes of its sector.

kind: update_address

kind: add_party

kind: remove_party

kind: add_option

kind: remove_option

kind: change_excess

kind: add_subject

kind: remove_subject

AmendAgreementParams

Requires a signed-in PAP session with write scope.

AmendmentTerms

AmendAgreementResult

Result of amend_agreement. The operation MUST have user_approval_required: true when pricing_after differs from pricing_before, when amount_due_now is set, or when a change adds or removes a party or a subject. A standing permission is not enough for these.

14.Errors (core)

OfapErrorCode

Type: one of not_licensed, not_available_in_region, product_not_found, offer_not_found, offer_expired, question_set_outdated, sensitive_field_received, documents_not_delivered, accuracy_not_confirmed, needs_assessment_invalid, agreement_not_found, amendment_not_allowed, not_supported.

OfapError

Error returned in an MCP tool result with isError: true, in structuredContent.error. PAP errors (insufficient_scope, sign_in_required, terms_changed) keep their PAP form.

15.Conversation binding (PROPOSED, NOT DECIDED)

ConversationData

PROPOSED. Some distributors expose only a company agent. If OFAP accepts them at level 2, each message that carries an OFAP object puts it here, in the message's structured data (data in a PAP conversation, structuredContent in a chat tool).

16.Tool index

ToolName

Type: one of get_distributor, list_products, get_documents, get_question_set, quote, submit_application, conclude, get_agreement, amend_agreement.

SessionRequirement

Session that a tool needs (PAP draft 0.2).

Type: one of none, signed_out_or_none, signed_in_read, signed_in_write.

ToolSignatures

Params and result type of each tool.