Schema reference, draft 0.1

Every type of AIP draft 0.1, generated from schema.ts and registry.ts through schema.json. The sections follow schema.ts, then registry.ts from R1. 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, quote and validate_answers
• 3 Subscribe: level 2, plus submit_application or conclude

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. A server at level 2 can give binding offers, because it implements validate_answers.

Type: one of 1, 2, 3.

InterfaceKind

How a distributor exposes the protocol.

Type: one of tools, conversation.

AipSettings

Settings object of the extension. A server puts it under capabilities.extensions["org.agenticinsuranceprotocol/aip"] 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}$.

SubdivisionCode

ISO 3166-2 subdivision code, upper case, for example "US-CA" for California.

Type: string. Pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$.

CurrencyCode

ISO 4217 currency code.

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

Lei

Legal Entity Identifier (ISO 17442): 18 letters or digits, then 2 check digits.

Type: string. Pattern: ^[A-Z0-9]{18}[0-9]{2}$.

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

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

InsuredFamily

Family of what a product insures: a kind of person, or a kind of good. Servers SHOULD use a value of KnownInsuredFamily. Other values MUST be lower case with underscores.

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

KnownInsuredFamily

Families that the known product lines need.

Type: one of person, organisation, pet, dwelling, contents, vehicle.

3.Distributor (level 1)

DistributorRole

Role of a party in the distribution chain. The provider roles are in ProviderRole.

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

RegisterIdentifierType

Kind of public register identifier.

Type: one of orias_number, siren, fca_frn, npn, dgsfp_key, naic_cocode, lei, other.

Licence

One entry in a public register that gives the right to sell a product, or to carry its risk.

GetDistributorParams

Params of get_distributor. No params.

Type: object.

GetDistributorResult

4.Products (level 1)

ProviderRole

Role of the party that carries the risk.

Type: insurer.

ProviderRef

The party that carries the risk.

SubscriptionPath

How a customer can subscribe to a product.

Type: one of conclude, application, handoff.

Product

UnderwritingScope

The risks a product can cover. list_products gives it with no customer data, so that an agent can drop a product that cannot cover the customer before it asks a question.

geography and insured are the structured part, which a machine can check against the answers. A server MUST NOT return an offer for a risk outside the structured part. An agent MUST NOT send answers to quote for a product whose structured part excludes the customer. conditions holds the rest.

Geography

Where the insured person lives, or where the insured good is.

InsuredType

A family of insured, and the kinds of it that a product covers.

ProductDetails

What the product covers, and the options a customer can add.

ListProductsParams

Params of list_products. Each filter is optional. The server MUST return only the products whose line and underwriting scope match every filter given.

ListProductsResult

5.Documents (level 1)

DocumentType

Kind of document.

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

InsuranceDocument

GetDocumentsParams

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

Variant 1

Variant 2

GetDocumentsResult

6.Question sets (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. AIP 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.

AnswerOrigin

Who produced the value of an answer.

Type: one of customer, agent, third_party.

AnswerSource

Where one answer comes from. validated_by_customer is true when the customer confirmed this value before the agent sent it. It is always true when the customer gave the value. An agent MUST NOT set validated_by_customer to true when the customer did not validate that answer.

origin: customer

origin: agent

origin: third_party

AnswerSources

The source of each answer, keyed like answers. An agent MUST give a source for each answer, and no source for a key that has no answer. Otherwise the server returns answers_invalid.

Type: map of AnswerSource.

7.Quote (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.

Without validation, every offer is indicative. To get binding offers, the agent first has the customer validate the answers with validate_answers, then sends the same answers and sources with that validation.

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.

When a server implements quote, an agent MUST take the price, the cover, the limits and the excess that it shows the customer from the offer, and MUST NOT take them from a page made for people.

QuoteResult

status: complete

status: needs_input

status: in_progress

NoOffer

Why no offer is possible.

NoOfferReason

Stable reason why no offer is possible. Servers SHOULD use a value of KnownNoOfferReason. Other values MUST be lower case with underscores.

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

KnownNoOfferReason

Common reason codes. outside_underwriting_scope means that the risk is outside the product's underwriting scope: its geography, its insured types or its conditions. A quote for a risk outside the structured part MUST get this reason.

Type: one of outside_underwriting_scope, risk_not_accepted, age_not_accepted, breed_not_accepted, claims_history_not_accepted.

8.Validation of the answers (level 2)

ValidateAnswersParams

Params of validate_answers. The agent calls it before it asks for binding offers, and before an application. The answers MUST be complete for the question set. Otherwise the server returns answers_invalid.

ValidationTerms

Terms of a validation: the answers that the customer validates, and their sources. The summary of the operation MUST show each answer and its source in plain words, so that the customer can check each one.

ValidateAnswersResult

Result of validate_answers. The operation MUST have user_approval_required: true, because only the customer can validate their answers. The agent MUST ask the person who will be the subscriber to approve it. When it succeeds, result.data holds a ValidationOutcome.

ValidationOutcome

AnswersValidation

The record that the customer validated a set of answers and their sources: a succeeded validate_answers operation. The server keeps it. The agent copies it into quote to get binding offers, and into the declaration of an application.

FieldIssue

9.Premium and cover

PremiumPeriod

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

Premium

CoverLimit

CoverSummary

ProductOption

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

Pricing

The price of an offer, and the cover it buys.

10.Parties, needs and consent

PartyRole

Role of a party in the agreement.

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

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

ContactConsent

The customer's choice about later contact.

DeliveredDocument

Declaration

The answers the customer commits to, with their sources and the customer's validation.

11.PAP operations and applications (level 3)

OperationState

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

Operation<ApplicationTerms>

A PAP operation. This mirrors the PAP operations extension (version 1). PAP is the authority for every field here except terms and aip_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 AIP tool.

Operation<ValidationTerms>

A PAP operation. This mirrors the PAP operations extension (version 1). PAP is the authority for every field here except terms and aip_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 AIP tool.

AipProgress

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

EvidenceRecord

What the distributor keeps when an operation succeeds. It links the exact revision the customer accepted to the documents, the declaration with its sources and its validation, the needs assessment, the consent and the underwriting scope. 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.Errors

AipErrorCode

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, answers_invalid, answers_not_validated, accuracy_not_confirmed, needs_assessment_invalid, not_supported.

AipError

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.

14.Conversation binding (PROPOSED, NOT DECIDED)

ConversationData

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

15.Tool index

ToolName

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

SessionRequirement

Session that a tool needs (PAP draft 0.2).

Type: one of none, signed_out_or_none.

ToolSignatures

Params and result type of each tool.

R1. Registry server

RegistrySettings

Settings object of the registry extension. The registry puts it under capabilities.extensions["org.agenticinsuranceprotocol/registry"] in its MCP server/discover response.

The registry SHOULD also serve the buyer skill through the MCP Skills extension (io.modelcontextprotocol/skills). An agent whose host loads skills over MCP then gets the whole skill from the registry, and get_country_rules serves the same country files to the other agents.

SourceAccess

How the registry reads a public register. The registry MUST read a register only through an access that the terms of the register allow, and under an agreement when the terms ask for one. Most registers forbid robots on their web pages.

Type: one of api, bulk_file, web_page.

RegisterCoverage

The kind of party that a register lists.

Type: one of intermediaries, insurers.

RegisterSource

A public register that the registry reads.

R2. Common types

DomainName

Host name, lower case, with no scheme, port or path, for example "pets.example.com".

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

RegisterIdentifier

An entry in a public register, as an agent or a listing gives it.

R3. Listing

ListedDistributor

A server that the registry lists.

ListingCheck

The last licence check of a listed server, for the country asked.

R4. Search

SearchDistributorsParams

Params of search_distributors. The params describe a market, never a person.

SearchDistributorsResult

Result of search_distributors.

• Each server in distributors MUST match every param of the search: the country is in its countries, the line is in its lines, the subdivision is in its subdivisions when it has some, the insured family is in its insured_families, and its level is not below min_conformance_level.
• The registry MUST return every listed server that matches, across the pages.
• For a country where it lists no server, the registry MUST return the error "country_not_covered", so that an agent does not read an empty list as "no seller exists".
• The order carries no meaning. The registry MUST NOT rank a server for a payment or for any commercial link. It SHOULD shuffle the order for each new search, and keep that order across the pages of the same search.
• An agent MUST NOT show the order to the customer as a ranking.
• A search result is not a licence check. An agent checks the seller with verify_licence before it sends any of the customer's answers.

R5. Licence check

SellerSubject

A seller to check. The domain is where the customer's answers go.

ProviderSubject

A provider to check, for example from Offer.provider. Give its domain, a register entry, or both.

Variant 1

Variant 2

DistributorCheckParams

Params of verify_licence for a seller. Every distribution role counts, including an insurer that sells its own products.

The check MUST work for a seller that the registry does not list. An agent can find a seller anywhere on the web, and the check matters most then.

ProviderCheckParams

Params of verify_licence for the party that carries the risk, for example the insurer in Offer.provider. Only a provider role counts.

VerifyLicenceParams

Params of verify_licence. The params name a company and a market, never a person. A seller check always names the domain that receives the customer's answers, because a register number alone does not prove who runs a website.

Type: DistributorCheckParams or ProviderCheckParams.

LicenceStatus

Status of one register entry, as the registry reads it.

Type: one of active, pending, lapsed, suspended, revoked, not_found, name_mismatch.

LicenceCheck

The result of reading one entry in one public register.

DomainLink

How the registry tied a domain to register entries. Only "register" and "confirmed" support the verdict "licensed".

Type: one of register, confirmed, claimed, not_linked.

CheckedSubject

What the registry found about the party it checked.

NotLicensedReason

Why a party holds no licence for what the agent asked.

Type: one of no_entry, licence_not_active, name_mismatch, role_not_covered, subdivision_not_covered, line_not_covered.

UnknownReason

Why the registry cannot decide.

Type: one of country_not_covered, subdivision_required, register_unavailable, subject_not_identified, domain_not_linked.

LicenceVerdict

The answer to the question of the agent.

verdict: licensed

verdict: not_licensed

verdict: unknown

VerifyLicenceResult

Result of verify_licence.

The registry tests each entry in this order. An entry covers the question when it passes all five tests: 1. Country: the entry exists, and its country is the country asked or its passports include it. 2. Subdivision: it has no subdivisions, or they include the subdivision asked. 3. Line: it has no lines, or no line is asked, or its lines include the line. 4. Role: for the capacity "provider", its role is a provider role. 5. Status: its status is "active".

The verdict:

• "licensed" when at least one entry covers the question and, if the params give a domain, domain_link is "register" or "confirmed".
• "unknown" when no entry covers the question and the registry could not read every register that applies, or could not identify the party. Also when an entry covers the question but the domain link is "claimed" or "not_linked".
• "not_licensed" in every other case: the registry read every register that applies, and no entry covers the question. The reason comes from the entry that passed the most tests, and names the first test it failed: country "no_entry", subdivision "subdivision_not_covered", line "line_not_covered", role "role_not_covered", status "name_mismatch" or "licence_not_active".

Rules for the registry:

• licences MUST list every entry that the registry read for the party in the registers that apply, including the entries that are not active.
• A verdict MUST rest only on reads made at most MAX_READ_AGE_DAYS days before checked_at. The registry SHOULD read the register again for each call when the register has an API or a web page.
• The registry SHOULD keep each result under its check_id for at least five years, so that it can confirm later what it said.

Rules for the agent:

• An agent MUST check the seller, in the capacity "distributor", before it sends any of the customer's answers to that seller. The domain MUST be the domain of the server or the website that receives the answers. The agent gives the customer's country, the subdivision where licences apply per subdivision, and SHOULD give the line.
• An agent MUST check the provider of an offer, in the capacity "provider", before it applies or concludes, when the provider is not the seller.
• On "not_licensed", the agent MUST NOT send the customer's answers to that party, and MUST NOT apply or conclude through it. It MUST tell the customer why.
• On "unknown", the agent MUST tell the customer that the licence could not be checked, and why. It MUST NOT apply or conclude, and SHOULD NOT send the customer's answers. It MAY ask the seller for its register identifier and check again.
• An agent MUST keep each result that it relies on with the record of the sale, and SHOULD give the customer a copy.

R6. Country rules

GetCountryRulesParams

Params of get_country_rules.

RulesStatus

Review state of a rules file.

Type: one of draft, endorsed.

RulesFile

One rules file of the buyer skill. The file is Markdown with a YAML front matter. The front matter holds country, version, owner, status, and endorsed_by and reviewed_at when they apply, with the same values as the fields of this object. It also holds subdivision and line for a file of a subdivision or of a line.

GetCountryRulesResult

Result of get_country_rules.

• files MUST start with the file of the country. The file of the subdivision and then the file of the line follow, when they exist.
• For a country with no rules file, the registry MUST return the error "country_not_covered".
• Each file MUST be the same text as the file of the same version in the skill, so that sha256 is the same in both places.
• An agent MUST follow every file of the result. When the registry does not answer, the agent uses the copy in its installed skill, and SHOULD tell the customer which version it used.

R7. Errors

RegistryErrorCode

Type: one of country_not_covered, invalid_params.

RegistryError

Error returned in an MCP tool result with isError: true, in structuredContent.error.

A registry tool MUST refuse a call with a param that this file does not define, and MUST NOT keep its value. That is how the registry stays free of customer data.

R8. Tool index

RegistryToolName

Type: one of search_distributors, verify_licence, get_country_rules.

RegistryToolSignatures

Params and result type of each registry tool.