Changelog
The standard and each profile version separately. A standard tag reads v1.5.0, a profile tag reads
vn-v0.2. See Versioning.
The standard
Section titled “The standard”v1.5.0-draft (unreleased)
Section titled “v1.5.0-draft (unreleased)”Trisilva’s work on top of the inherited OPIN v1.2.1 vocabulary, published openly. The first release on this standard in four years.
The version stays on the 1.x line because nothing inherited was removed or renamed, and it skips 1.3 and 1.4 so the Open Insurance Initiative keeps room on its own line. See Versioning.
Five internal contradictions closed
Section titled “Five internal contradictions closed”Each of these was a place where two parts of the standard said different things, so an implementer had to pick one and could not know what a counterparty had picked. All five are additive: nothing is renamed or removed, and no inherited wire name changes.
claimsOccurrenceis the two-value enumeration everywhere. It was a Boolean oncyberLiabilityCoverageand the enumeration onpropertyCoverageandbusinessInterruptionCoverage. A Boolean cannot carry which of claims-occurring and claims-made applies without a convention agreed out of band, and reading it wrongly assigns a claim to the wrong policy year. Cyber is the line where it matters most, because a breach is routinely found long after the intrusion. Closes concern 3.policyWordingcarriesversionandeffectiveDate. It held a name alone, which meant a wording could not be traced to the version in force on a given date. That is a routine compliance ask, and the API resource model already showed both fields. Closes concern 16.termLifeCoveragecarries a multi-valuedbeneficiaryreference. TheBeneficiaryentity existed in module 1 and term life is the case it was built for, and no field connected them. The resource model drew the relationship the schema did not have.businessInterruptionCoveragecarriespropertyRef. The cover only makes sense attached to a premises, and nothing linked it to one.travelCoveragehas an:endorseaction. Every other coverage type had one, and travel’s own lifecycle diagram showed an extension reached through it while the endpoint list did not carry it.
The documentation was rewritten for readers who are new to insurance
Section titled “The documentation was rewritten for readers who are new to insurance”The modules assumed an insurance vocabulary most of their readers do not have. A new Insurance concepts defines it once: the parties, the policy, the money, the claim and reinsurance, plus the abbreviations the modules use without expanding.
Each module now opens by saying what that line of business is and how its model is shaped, then
lists what to watch when implementing it. Provenance annotations ([OPIN], [added],
[normalisation], [OPIN concern]) are gone from the module pages, along with the defect numbers
they carried, because that record belongs in this changelog and in
inherited/ rather than inline in a page someone is reading to build
against. Every warning survived the move, restated as a property of the standard today.
Lifecycle diagrams are now marked normative on every module, which is one of the two conditions in Versioning for leaving draft.
The base URL and the scope names are marked as deployment-issued
Section titled “The base URL and the scope names are marked as deployment-issued”Conventions printed one base URL and two scope literals in a form a reader could take for the values to send. Both are per deployment, and a caller who built them from the page reached nothing.
The standard fixes everything from /v1 onward and the module paths over it. The host in front of
those paths belongs to whoever deployed the API, and the two scope names describe the read-against-write
division rather than the strings on the wire. Both now say so, and both point the reader at what was
issued with their credentials.
The opin-vn host form is kept, because it is in service and changing a base URL breaks every
caller. It is no longer written as an instruction to reproduce it: an implementation that has not
shipped is free to use its own name.
The wire is unchanged, so this is a documentation correction under Versioning.
Two version lines became one
Section titled “Two version lines became one”The Open Insurance Initiative published the data standard at v1.2.1 and the API specification at
v1.0, separately. That is how they came to disagree with each other about termLifeType and
termLifeRiders, recorded as concern 1 of the twenty inherited. They are now one standard on one
version line.
Base-layer work moved out of the Vietnam profile
Section titled “Base-layer work moved out of the Vietnam profile”Authentication, the error model, cursor pagination, idempotency, item-level operations, lifecycle endpoints and claim-to-coverage linkage were previously filed as the Vietnam market profile. None of them are Vietnamese. Every market needs all of them, and they sat in a profile only because the standard could not be changed at the time.
They are now in the standard. The Vietnam profile keeps only what is specific to Vietnam, which is close to nothing until the statutory work is done. See Vietnam.
This is the largest change in the version and it is a relocation, not a rewrite. No content was altered in the move.
One directory per module, at the root of the repository
Section titled “One directory per module, at the root of the repository”The standard was two documents of about fourteen hundred lines each, one for the data model and one for the API, each organised by the same twelve modules. A reader building one coverage line had to work both documents in parallel.
It is now one directory per module, holding that module’s data model, its API surface and a README naming what to check before implementing it. Those twelve directories sit at the root of the repository, because the standard is what the repository is for and it should be the first thing visible in it. What applies to every module was lifted out beside them, to Conventions, Across the modules and Scope and design.
Everything that is not the standard is in project/: governance, versioning,
conformance, the inherited material and the market profiles. Contributing, the code of conduct and
the security policy are in .github/, where GitHub reads them natively. MAINTAINERS.md was two
one-row tables and is now part of Governance, which already carried
the reasoning behind both.
The split is a relocation. No normative content was rewritten in the move.
No directory per version
Section titled “No directory per version”standard/v1.5.0-draft/ is gone and the working tree carries one version of the standard, the
current one. Released versions are reachable by git tag and recorded here. A copy of the whole
standard per release accumulates trees nobody reads.
Versioning carries the reasoning.
Country tracks became market profiles
Section titled “Country tracks became market profiles”tracks/ is now markets/ and the layer is called a market profile.
The old name had to be explained before the thing it named could be, and
Conformance already called the third conformance level “market”.
Profile version tags are unchanged, so vn-v0.2 still reads vn-v0.2.
The profiles are a peer layer to the standard, and they are filed under project/ only because
there is one of them and it is nearly empty. project/markets/README.md records what moves them
back to the root. The _template/ scaffold is gone; what a profile contains is described in that
same README rather than mocked up as empty files.
The annotation markers no longer name a retired market profile
Section titled “The annotation markers no longer name a retired market profile”Every line in the standard carries a marker saying where it came from. Two of them named the Vietnam track, which stopped owning this material when the base-layer work moved into the standard. They are swept, in prose only, across all twelve modules:
| Was | Is |
|---|---|
[OPIN-VN extension to API; OPIN schema reused] | [added] |
[OPIN-VN normalisation] | [normalisation] |
[OPIN-VN] | [added] |
A normalisation is a spelling correction rather than an addition, so it did not collapse into
[added] the way the earlier note said it would. Two markers describing two different things is the
point of having markers.
Prose that named OPIN-VN as the actor was rewritten the same way, because a market profile was
being credited with decisions that belong to the standard. The annotation table in
Conventions is rewritten to match.
The three wire identifiers were deliberately not touched. api.opin-vn.{tld}, opin-vn.admin
and opin-vn.developer still carry the retired name. They travel on the wire, so correcting them
breaks every caller, and they stay held for a major version alongside the misspelled field names.
See Scope and design. Nothing in this sweep changes what an implementation sends.
Defects are this standard’s to fix, not a report to a dormant upstream
Section titled “Defects are this standard’s to fix, not a report to a dormant upstream”The documents still described themselves as a downstream track filing defects with a live Open Insurance Initiative that would publish an OPIN v1.1 to fix them. That was the position before this repository took the standard forward, and it survived the earlier moves because it is a change of meaning rather than of naming. Thirty-five places, across all twelve modules, Conventions, Scope and design and both concern catalogues.
Upstream candidate became Change proposal on twenty-eight concerns, because there is no upstream
to send them to any more: this is it. A future v1.0 of this track must resolve this upstream with the OPIN initiative now names the inherited defect number and states the position this version
takes. An OPIN v1.1 should add an explicit linkage field to Claim is closed outright by the
policyNumber uniqueness rule.
concerns-v1.2.1 no longer says it is
published so the initiative can resolve the defects at source, and its duplicated intro paragraph is
gone.
None of this makes the initiative disappear from the record. It is still credited as the origin in The standard and inherited/, and Versioning still leaves 1.3 and 1.4 unclaimed so it has room if it publishes again. What changed is that nothing here waits on that happening.
Two things were corrected while in there. The cyber liability module said a future publication should consider breach-notification timelines, which contradicted the scope boundary, where those are listed as out of scope by design and never to be closed; the module now matches.
KNOWN-GAPS.md became SCOPE.md
Section titled “KNOWN-GAPS.md became SCOPE.md”Same material, and a different job. The file held four things: how the entities link, what is
settled by convention, what is held for a major version, and what the standard will never cover.
Three of those four are decisions rather than gaps, and filing them under a name that says “gaps”
described the standard as a set of holes with some prose around them. SCOPE.md says what the file
does, which is draw the boundary. The page publishes at /docs/standard/scope, and the old path
redirects. And
conventions.md said an OPIN v1.1 should declare authentication, the error model, pagination and
idempotency, in the same file that declares all four of them.
Inherited
Section titled “Inherited”The data standard v1.2.1 and API specification v1.0 are kept unmodified in inherited/, with the twenty catalogued defects at concerns-v1.2.1 and fourteen against the API specification at concerns-api-v1.0. The API list was previously an appendix inside the API document and had no home of its own.
Structural defects closed
Section titled “Structural defects closed”Claim-to-coverage and receipt-to-obligation linkage. The inherited schema declared no foreign
key from Claim to a coverage and none from Receipt to the policy or claim that produced it, and
inferred both from correlation. This version declares the constraint the model was already
assuming: policyNumber is globally unique across the namespace, it travels in the payload where
the linkage matters, and /claim and /receipt expose ?policyNumber= and ?claimNumber= as
collection filters. Closes inherited defects 12 and 13.
Trade credit lifecycle. tradeCreditCoverage was the only coverage entity of the eight carrying
no inceptionDate, expiryDate, status, or premium, brokerage and endorsement fields, which left
it describing a credit limit with no policy around it. All thirteen are supplied, with the names,
types and value sets they carry everywhere else. Closes inherited defect 7.
Lifecycle transitions are normative. The state diagrams in each module’s API page were previously a conservative reading with no normative force, so two conformant implementations could disagree about whether a transition was legal. They are now normative. A transition they do not draw is not a transition an implementation may make.
The naming rule is settled. The data model and the API design took opposite positions on whether
misspelled inherited field names are corrected or preserved. The rule is now stated once: the API
governs anything that travels on the wire, and the data model governs what a field means. A
[normalisation] records what the field should have been called and never changes what an
implementation sends. See Conventions.
The remaining inherited defects are compatibility breaks held for the next major version, so that an implementer absorbs them together rather than one at a time. They are in Scope and design.
Vietnam profile
Section titled “Vietnam profile”vn-v0.2 (2026-04-29, amended)
Section titled “vn-v0.2 (2026-04-29, amended)”Published as OPIN-VN v0.2. Everything in it that was base-standard work has since moved to the standard at v1.5.0. What remains is what is genuinely Vietnamese: money, addresses, identity documents, statutory claim handling and personal data.
Original v0.2 scope, for the record: endpoint completion to close the gap between OPIN’s full data standard and its partial v1.0 API specification. No new entity schemas and no vendor product behaviour. Twenty structural concerns in OPIN catalogued. Known gaps published.
Deliberately not carried forward from the earlier draft: coverage extensions that would have pulled distribution, commission and product-specific behaviour into the profile.