OPIN: carrying an open insurance standard forward, and authoring the profile each market needs.
The standard is at v1.5.0-draft and Vietnam's profile sits on top of it at v0.2. What the standard settles, where it is still thin, and what an open licence does and does not protect an insurer from.
Integrating a partner isn’t new to you. Your team has done it many times before. Whether it’s an insurer, a bank, a distribution channel, or a repair network, you’ve done it and you are familiar with how it works. But while the entity names lined up, the field mappings were agreed upon in a workshop, the integration still took longer than anyone planned.
The overrun is rarely discussed in the vocabulary. It’s the layers underneath it: whose token format, what a failure response looks like, whether a retried request issues a second policy, how a claim arriving at eleven at night finds the coverage it belongs to. Those questions get answered inside every integration, one at a time, by whoever is in the room that week. The answer is then maintained for as long as the integration lives, and it is invisible to everyone except the two teams involved with it.
An open standard settles those questions once, in the open, for everyone who implements it.
What each tier is allowed to do
The stack under Trisilva's products has three layers. Each one strictly extends and supports the layer below rather than reinterpreting it.
- Tier 1 is OPIN: This is the open insurance standard. It defines the shared vocabulary across twelve modules and roughly thirty entities: what a claim is, what a receipt is, who the parties to a policy are. The Open Insurance Initiative created it and published it between 2018 and 2022, reaching v1.2.1 on the data standard and v1.0 on the API specification. Neither document has been revised since, which leaves twenty structural defects in the data standard and fourteen in the API specification with no route to a fix. Trisilva now carries the standard forward at v1.5.0-draft, publishes it under MPL 2.0, and credits the initiative as its origin. A defect gets fixed at source rather than patched privately inside every integration that meets it.
- Tier 2 is the market profile: Only what one market requires and other markets do not: statutory claim handling, data residency, identity documents, currency and addresses. Vietnam is the first profile, at v0.2.
- Tier 3 is the platform layer: Trisilva's is InsureFlow: deployment across regions, connectors to existing systems, tenant identity, audit logging, document handling. This is the real work, where none of it belongs in the standard or in a profile.
That third line is crucial and is worth checking rather than taking on trust. Read any open standard with one question: is anything in it specific only to one vendor's platform? Nothing in OPIN should be. The test should be written into the project's own governance and applied to every proposal including Trisilva's. Would a market with no Trisilva software in it need this?
If something were to fail that test, it is a defect and the issue tracker is the place to say so.
What the standard settles
v1.5.0-draft does one thing: it completes the API surface to match the data standard without adding new entities.
That is a larger job than it sounds, because the inherited API coverage is uneven. Only the motor module carries endpoints which are addresses a system actually calls to read or write a record. Everywhere else the standard publishes the entity schemas, the field-by-field definition of each record, with no endpoints to move them. The vocabulary exists but the wire contract does not.
There are seven questions that get answered, each with a consequence a delivery team will recognise.
| Question | What the standard settles | What it changes for a delivery team |
|---|---|---|
| Authentication | OAuth 2.0 bearer tokens, with two permission levels matching the two roles the standard already declares | Your partner's onboarding stops being a bespoke conversation |
| Error model | RFC 7807 Problem Details, a published format for machine-readable errors | Your operations team can tell a rejected claim from a partner outage without telephoning anyone |
| Pagination | A cursor, a pointer to the last record you received. It supersedes the inherited skip and limit, which stay accepted as a fallback | A nightly reconciliation pull stops silently skipping records written while it ran |
| Idempotency | A key on write operations | A timeout followed by a retry does not become a second policy |
| Item-level operations | Addressing a single record where the inherited specification addresses only the whole collection | Changing one line does not mean resending the set |
| Lifecycle endpoints | The whole life of a record rather than its creation alone, as colon-action calls for cancellation, renewal, endorsement, settlement, reopening and refund | A state change travels over the wire rather than being agreed out of band |
| Claim-to-coverage linkage | The central relationship in any claims system, and the one the inherited model leaves implicit | At this version it is settled by convention rather than in the schema. See the gaps below |
Four of the seven are visible in a single exchange. A state change is a colon-action call, the write carries an idempotency key so a retry cannot duplicate it, and the refusal returns in a published error format rather than as prose:
POST /motorCoverage/6f9619ff-8b86-d011-b42d-00c04fc964ff:cancel
Authorization: Bearer <token with scope opin-vn.admin>
Idempotency-Key: 9f2c1a04-3e77-4b8e-9a51-0b6d2c8f4a10
Content-Type: application/json
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Coverage is not in force",
"status": 409,
"detail": "This coverage is already Cancelled, so :cancel does not apply.",
"instance": "/motorCoverage/6f9619ff-8b86-d011-b42d-00c04fc964ff:cancel"
}All seven surfaced while authoring Vietnam's profile, and all seven were filed there first. They have since moved into the standard, because none of them is Vietnamese. Authentication, error handling, pagination and record lifecycles face the same problems in Hanoi and in Manila.
A profile is for what’s unique to that market, so material that every market requires belongs a tier down, ensuring that it is the standard across all markets. That is the scope test doing its work on Trisilva's own filing rather than on someone else's proposal.
What Vietnam's profile covers today
To be honest, the Vietnamese profile currently covers very little. And it’s more of a status quo rather than work that has stalled.
At v0.1 the profile carried the seven settlements above, plus the data model rendered consistently. All of it has moved to the standard. What remains is what is genuinely specific to Vietnam, and most of it has not been written yet. Five items are named in the profile so that a reader can see the shape of the work and check the gaps:
- Statutory claim handling. Decree 67/2023/ND-CP governs claims settlement in Vietnam. What it requires of a response timeframe is being confirmed with Vietnamese counsel, and nothing goes into the profile before that confirmation.
- Personal data. Law 91/2025 carries residency and handling obligations that affect what an implementation may transmit and where it may hold it.
- Identity documents. The party model needs the document types Vietnam actually uses, and the standard's enum is not built around them.
- Currency and money. Vietnamese dong is unit-denominated and does not carry minor units the way the standard's money handling assumes. That has a wire consequence and needs stating.
- Addresses. Vietnam's administrative structure does not map onto the standard's address shape without a decision about how it is carried.
None of the five is specified, and the profile says so on its own front page. Nobody is named as accountable for it yet either, which matters for a document that will eventually make claims about a market's regulation.
So if you are building in Vietnam today, the standard is what you implement. The profile is what sits on top of it.
Where the gaps are
v1.5.0-draft is complete enough to build against. It also has four holes worth knowing before you commit, and they are listed in the standard's own known-gaps page.
| Gap | What happens | What to do until it is fixed |
|---|---|---|
| Two important links live in the request rather than in the data model | Claim-to-coverage, and receipt-to-policy, which is the question of which payment belongs to which policy, are carried as an agreed field inside the request body. policyNumber is treated as globally unique to make that work. The schema does not declare it, so an implementation can be fully conformant and still fail to interoperate | Pin it in your own integration contract. Tightening it into a normative schema note is the first item on the next patch |
| Lifecycle transitions are implied rather than declared | The state diagrams walk the transitions conservatively without stating them as requirements. Two conformant implementations can disagree about whether a cancelled policy may be reinstated | Budget a bilateral decision on transitions. You will find this in acceptance testing, not in the specification |
| Trade credit is not usable yet | Module 9 inherits structural holes: no inception date, no expiry date, no status, and no premium or endorsement fields | Treat it as vocabulary only. It cannot serve as a wire contract at this version |
| The two documents disagree about misspelled field names | The inherited specification carries genuine spelling errors in field names. The data schema corrects them and records each original beside it; the API design preserves them exactly, on the grounds that they are already live in every existing implementation. Both positions are defensible and they cannot both govern one standard | Treat the API design as authoritative for anything travelling on the wire |
One more thing a reader will meet in the specification and should know the reason for. Three identifiers still carry opin-vn: the base URL, and the two OAuth scopes in the example above.
That material is base-standard work and applies to every market, so the names are wrong. They are not corrected here, because changing a base URL or a scope name breaks every caller, which makes it a major change however small the edit looks.
They ship corrected with the other held breaks, together, so an implementer absorbs one change instead of three. Everywhere else the retired name is already gone, which leaves one question to ask about any opin-vn string rather than two: if it travels on the wire it is held, and if it does not it has been swept.
Why it is published openly
A shared model is worth having because nobody can take it away.
The standard sits in a public repository under MPL 2.0, the more restrictive of the two licences on the inherited documents, whose data standard is MPL 2.0 and whose API specification is Apache 2.0. That licence cannot be revoked. An insurer that builds to OPIN owns what it built, and if that insurer later works with a different supplier, the model goes with it.
What openness does not cover
There are two things, and both are fair to inquire before adopting anything.
A licence removes revocation risk, not abandonment risk. MPL 2.0 guarantees that what is published stays published and usable. It guarantees nothing about maintenance. If Vietnamese regulation moves in 2027 and the standard does not move with it, an insurer holds a preserved artefact rather than a current one.
Today that risk sits with Trisilva's continued authorship. A second maintainer would reduce it. A stronger licence won’t.
One author means one author. Trisilva does the editorial work and holds the only editor seat. There are no other maintainers and external implementers on record. A standard with a single implementer is a specification with a licence file attached, and it becomes a standard when somebody else ships against it and argues about it. The condition for that is written into the governance document rather than left vague: two independent implementers, or one sustained outside contributor, and editorship opens. It is written down so it can be held against us.
Against both, one thing genuinely reduces the exposure: you can take the seven settlements separately. Taking the error model does not commit you to the lifecycle endpoints, and taking authentication does not commit you to anything else. You can adopt one piece at a time, so the decision in front of you is smaller than adopting a standard.
What to do with it
Take the seven settled questions and check them against what your current integrations already do. Where they agree, you have less work ahead than you thought. Where they do not, you have found a decision worth settling before the next partner rather than during it. That costs an afternoon and returns a finding either way.
Then, if you disagree with any of it, say so in the open. Anything marked as an addition rather than as inherited is explicitly open to argument, and every accepted change records why against the defect it closes, so an objection has something to land on. A well-argued one should be expected to change the document.
Read the standard: github.com/trisilva/opin. Twelve modules at the root, the market profiles under project/markets/, Vietnam at v0.2.