Interface (OpenAPI)

The services of OMDS LD are described in an OpenAPI file. It is the contract of the structure: operations, paths, status codes, error objects and examples. The behaviour of the operations is explained on the pages on process knowledge and product knowledge.

State of implementation: the file is a draft. It describes the operations the sample insurer offers; further business objects such as offer and application follow by the same rules.

Paths and methods

  • Paths name resources, not messages: /products, /tariff-inquiry, /calculations, /business-cases/{caseId}/calculation.

  • The method follows the meaning. GET reads and is cacheable; the inputs of an inquiry are query parameters, such as GET /products?date=2022-06-01. POST on a collection creates a business object and answers with 201 Created and its address in Location. The tariff inquiry is a POST because it needs a complete instance as body; it stores nothing all the same.

  • Edits are named methods of the business object: POST /business-cases/{caseId}/calculation:addComponent. The name after the colon is the operationId.

  • The IRI of a business object is its address. GET on the IRI of the calculation returns the calculation; the nodes of its draft lie below it (…/calculation/instance, …/calculation/c1).

  • Nothing twice. What the path names, such as the business case, is not repeated in the body.

  • Inquiries show the way on. listProducts names every product with its label and the next steps readProductKnowledge, readDefaultInstance and, with the draft at the server, createCalculation. readDefaultInstance gives the default instance – mandatory components in their minimum number, attributes with their defaults – with the IRIs of the tariff inquiry (…/tariff-inquiry#instance, #c1). With the risk objects added, it is the body of inquireTariff; the next step names the shapes of the risk objects. The risk object rule bc:riskObjectRule at a node says that the risk objects are assigned there with i:riskObject, mostly at the root.

Operation Method and path

listProducts, readProductKnowledge, readDefaultInstance

GET /products, /products/knowledge, /products/default-instance with date and product

inquireTariff

POST /tariff-inquiry

createCalculation

POST /calculations

readBusinessObject, calculatePremium

GET /business-cases/{caseId}/calculation, …/premium

addComponent, removeComponent, setAttributeValue, createRiskObject, assignRiskObject, removeRiskObject

POST /business-cases/{caseId}/calculation:<operationId>

readProcessKnowledge, readCodelist, readTemplates

GET /process-knowledge, /codelists/{name}, /templates/{name}

Three ways in

Way in Purpose

Reference page

For reading: all operations with description, status codes and examples. The page makes no calls.

omds-ld.yaml

Machine-readable, with embedded examples: for code generators, own tools and AI agents.

API explorer

For trying out on the example server: the operations can be called against the three example insurers, with the examples pre-filled.

The API explorer suits single calls. Playing a draft through several steps there means carrying the identifier of the business case from call to call; the sample broker with its draft editor is the better way for that.

Structure of the file

  • Payloads are JSON-LD (application/ld+json) in the vocabulary of the norm. Their structure is defined by the SHACL shapes. The extension x-omds-request-shape names the shape of the request per operation. The request shapes are part of the norm, in SHACL Core; a client or AI agent checks a request with them before sending it, including whether a predicate is misspelt. x-omds-request-shape-from-catalogue marks operations for which the catalogue of the insurer adds shapes of its own, for instance for the vehicle templates.

  • Request schemas. The body of every operation with a request is described by a JSON Schema (2020-12) generated from its request shape, in the canonical form. The reference page thus lists the fields per operation, code generators and MCP servers get an input schema. The JSON Schema checks the structure; the shape remains authoritative. The answers are JSON-LD without a schema of their own.

  • Next steps. Every answer about a business case names the admissible next steps (bc:nextStep). Their bc:operation is the operationId of the OpenAPI file and bc:expects one of the shapes in x-omds-request-shape. A client follows the next steps instead of knowing the process in advance. For AI agents the operationId is also the name of the tool of an MCP server built on the OpenAPI file.

  • Operation kinds. x-omds-operation-kind assigns every operation to an operation kind: inquiry, creation and editing.

  • Errors are problem details according to RFC 9457 with a type below https://vvo.at/omds/ld/problems/, such as target-not-in-draft or wrong-state. A rejected request changes nothing.

  • Examples. Every operation has an example for request and answer. Every example answer is the actual answer of the sample insurer to the example request, with the business case https://insurer.example/omds-ld/api/business-cases/4711.

Canonical form of the requests

A request can be written in JSON-LD in many ways. The norm defines one form, which its examples show and its request schemas describe:

  • "@context" refers to the normative context https://vvo.at/omds/ld/context.jsonld. It contains the prefixes of the vocabularies of the norm and defines for the predicates of the request shapes whether their value is an IRI, a date or a set. The IRI is a name: servers and clients map it to their copy of the norm and do not load it from the network. A copy is next to the reference page (context.jsonld), as are the request schemas (schemas/<class>.schema.json).

  • Classes and predicates are CURIEs (bc:AddComponentRequest, bc:target), IRIs and dates are strings. IRIs from the catalogues of the insurers are written out. The value of an attribute (bc:value) is a value object with @value and @type, because its datatype depends on the attribute.

  • A predicate that can have several values is always an array, also with one value (bc:riskObject).

  • The tariff inquiry sends the instance as @graph with exactly one node i:Instance and its parts.

{
  "@context": "https://vvo.at/omds/ld/context.jsonld",
  "@type": "bc:AddComponentRequest",
  "bc:target": "https://insurer.example/omds-ld/api/business-cases/4711/calculation/instance",
  "bc:component": "https://vvo.at/omds/ld/example/disrupto#ProdElement34"
}

Any other JSON-LD that expands to the same graph is a valid request too, for instance with an inline context of its own. An insurer loads no remote context other than the normative one.