<!-- markdown mirror of https://mintid.net/en/sdk/verifier-service-contract — generated at build time -->

> The freeze of the verifier-service OpenAPI contract at v1: three operations, a closed reason-code vocabulary, and the invariants the freeze locks in for every client in every language.

index — 12 documents

1.  [overviewsdk/00](/en/sdk)
2.  [getting startedsdk/01](/en/sdk/getting-started)
3.  [python sdksdk/02](/en/sdk/python)
4.  [service modesdk/03](/en/sdk/service-mode)
5.  [typescript clientsdk/04](/en/sdk/typescript-client)
6.  [mcp serversdk/mcp](/en/sdk/mcp-server)
7.  [conformancesdk/05](/en/sdk/conformance)
8.  [reason codessdk/06](/en/sdk/reason-codes)
9.  [record · assurance vocabularyrecord/01](/en/sdk/kyc-trust-model)
10.  [record · packagingrecord/02](/en/sdk/packaging)
11.  [record · multi-languagerecord/03](/en/sdk/multi-language-clients)
12.  [record · service contractrecord/04](/en/sdk/verifier-service-contract)
     *   [what is frozen](#frozen)
     *   [why freeze now](#why)
     *   [locked invariants](#invariants)
     *   [post-freeze changelog](#changelog)

SDK docs · record/04

# Decision record — the verifier service contract

The freeze of the verifier-service OpenAPI contract at v1: three operations, a closed reason-code vocabulary, and the invariants the freeze locks in for every client in every language.

## What is being frozen

_Status: **Accepted** (2026-07-21) — contract v1 frozen at 1.0.0 · depends on the specification’s presentation rules, decision records, paid-verification permission and single-core rule_

The OpenAPI document [`verifier-service.v1.yaml`](https://mintid.net/openapi/verifier-service.v1.yaml) at contract version **1.0.0**: three operations (`getBuildInfo`, `createChallenge`, `validatePresentation`), their schemas, and the closed `ReasonCode` vocabulary — byte-identical to the reason codes the embedded SDK emits.

Freezing means: any change to decision semantics or the reason vocabulary is a **major** contract version (the SDK’s semver policy, applied at the contract level); additive, non-semantic surface is **minor**. Transport-only clients, in every language, build against the frozen contract.

## Why freeze now

The multi-language strategy makes this contract the load-bearing artifact of the whole approach: it is the boundary that guarantees no client ever carries cryptography or policy. The nine acceptance conditions, the 10-second constant and the retention schema sit _behind_ the contract and are deliberately unexpressible in it: no lifetime parameter, no skip flags, no per-request height-lag override.

A contract test enforces route-for-route and code-for-code agreement between the YAML and the running service, so the frozen document is checked against reality on every CI run.

## Invariants the freeze locks in

*   **One decision path:** `validatePresentation` responses are the embedded SDK’s decision verbatim; HTTP 400 exists only where no session identity can exist — nothing parseable means no retention record.
*   **Closed reason vocabulary** shared with the conformance vectors; any change is major and flows to every language at once.
*   **Challenge identity** (verifier id, exact origin, request key) is deployment configuration bound to on-chain registrations — never caller input.
*   **`build-info` exposes exactly the release pins** — enough for a client to verify what it talks to, never secrets.

## Post-freeze changelog

Version

Date

Change

`1.0.0`

2026-07-21

Contract frozen (this record).

`1.1.0`

2026-07-21

Additive minor: `BuildInfo` gains required `conformance_suite_version`. No decision-semantics or reason-code change.

The freeze is what lets every client — in any language — treat the service surface as a stable fact: the conformance suite, the reason-code page and the service-mode guide in these docs all build on it.

[previous← record · multi-language](/en/sdk/multi-language-clients)

---
Source: https://mintid.net/en/sdk/verifier-service-contract · Decision record — the verifier service contract — MintID verifier SDK docs