Context
JSON Schema is used for defining specifications of messages regarding structures, entities and attributes. The use of JSON Schema promotes the preparation of unambiguous specifications. In addition, JSON Schema can be used as a basis for automated checking of messages, databases and dialogues. For example: data types and codelists for attributes, the number of allowed repetitions of entities and the mandatory or optional nature of attributes. AFD uses JSON Schema to oblige the presence of certain attributes when using an entityType and to define data types that attribute values must comply with. Below are some examples of JSON Schema. More detailed and/or technical information can be found at the JSON Schema website.
JSON Schemas within SIVI AFS
Within SIVI AFS we use JSON Schema on two levels. JSON Schemas for a certain structure or message are called baselines and are created and managed by SIVI. Based on those baselines, parties themselves can build their own AFD definitions for (for example) a product or service. AFD definitions are JSON Schemas which form a subset of a specific SIVI baseline.
Baselines
In baselines, SIVI defines the possible entities and attributes, as well as the cardinality and coherence between them, within a certain kind of message or structure. These baselines form the input of AOS, in which the parties themselves can compile AFD definitions based on (a subset of) this baseline. Many baselines are simple in design: at the top level, one main entity is allowed, in addition to some meta and process entities such as commonFunctional, commonTechnical, process, and document. Within the entities and entityTypes, all attributes available in the data catalog are allowed.
SIVI creates baselines for message structures in combination with a particular domain. Examples are the baselines for policyStructure-motorVehicle, policyStructure-income and policyStructure-health, while for (for example) the ticketStructure there is only one general baseline. On request, SIVI creates a new baseline: for example, if you want to use a structure that does not yet exist, or a domain that has not yet been worked out within an already existing structure, to create an AFD-definition.
Baselines are not downloadable, but are available on request as JSON Schema. All existing baselines are also loaded in AOS.
AFD definitions
In the AOS tool, organizations can create their own AFD definitions for their own products, web services, functions and the like. The output of this tool is an AFD definition as a JSON Schema, against which you can validate AFD messages and on the basis of which you can set up screens, APIs and tooling.
Below is a (very minimal) example of such an AFD definition. In this example, a submitClaim function that uses the claimStructure baseline:
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"description": "JSON Schema SIVI 2.0",
"//comment": {
"functionDescription": "submitClaim_fnol_request"
},
"definitions": {
"commonFunctional": {
"type": "object",
"additionalProperties": false,
"properties": {
"entityType": {
"description": "Unique identification of an entity. (NL: De unieke identificatie van een entiteit.)",
"type": "string",
"const": "default"
}
},
"required": [
"entityType"
]
},
"claim": {
"type": "object",
"additionalProperties": false,
"properties": {
"entityType": {
"description": "Unique identification of an entity. (NL: De unieke identificatie van een entiteit.)",
"type": "string",
"const": "default"
},
"repairStatus": {
"description": "Progress status (NL: Status voortgang)",
"codelistName": "ADNSVT",
"$ref": "test%2025-1-submitClaim_fnol_request-afdCodelists.json#/definitions/ADNSVT",
"type": "string"
},
"settlementTimeInMonths": {
"description": "Estimation in months of period expected by parties involved to settle the claim. (NL: Indicatie van hoe lang de betrokken partijen nodig denken te hebben voor de afwikkeling van de schade. Wordt ingeschat in maanden.)",
"type": "integer"
},
"thirdPartyLiable": {
"description": "Indication of third party liability. (NL: Indicatie die aangeeft of een derde partij aansprakelijk is.)",
"type": "boolean"
},
"incident": {
"type": "array",
"uniqueItems": true,
"allOf": [
{
"minContains": 0,
"maxContains": 1,
"contains": {
"$ref": "#/definitions/incident"
}
}
]
},
"party": {
"type": "array",
"uniqueItems": true,
"allOf": [
{
"minContains": 0,
"maxContains": 1,
"contains": {
"$ref": "#/definitions/partyCounterparty"
}
},
{
"minContains": 0,
"maxContains": 1,
"contains": {
"$ref": "#/definitions/partyWitness"
}
}
]
}
},
"required": [
"entityType"
]
},
"incident": {
"type": "object",
"additionalProperties": false,
"properties": {
"entityType": {
"description": "Unique identification of an entity. (NL: De unieke identificatie van een entiteit.)",
"type": "string",
"const": "default"
},
"incidentDate": {
"description": "Date when the incident occurred. (NL: Datum waarop het incident heeft plaatsgevonden.)",
"type": "string"
}
},
"required": [
"entityType"
]
},
"partyCounterparty": {
"type": "object",
"additionalProperties": false,
"properties": {
"entityType": {
"description": "Unique identification of an entity. (NL: De unieke identificatie van een entiteit.)",
"type": "string",
"const": "counterparty"
},
"fullName": {
"description": "First name and surname of a natural person completely written out. (NL: Voornaam en achternaam volledig uitgeschreven bij natuurlijke personen.)",
"type": "string"
},
"birthDate": {
"description": "Date of birth. (NL: Geboortedatum)",
"type": "string"
}
},
"required": [
"entityType",
"fullName",
"birthDate"
]
},
"partyWitness": {
"type": "object",
"additionalProperties": false,
"properties": {
"entityType": {
"description": "Unique identification of an entity. (NL: De unieke identificatie van een entiteit.)",
"type": "string",
"const": "witness"
},
"fullName": {
"description": "First name and surname of a natural person completely written out. (NL: Voornaam en achternaam volledig uitgeschreven bij natuurlijke personen.)",
"type": "string"
}
},
"required": [
"entityType",
"fullName"
]
}
},
"type": "object",
"additionalProperties": false,
"properties": {
"commonFunctional": {
"type": "array",
"uniqueItems": true,
"allOf": [
{
"minContains": 1,
"maxContains": 1,
"contains": {
"$ref": "#/definitions/commonFunctional"
}
}
]
},
"claim": {
"type": "array",
"uniqueItems": true,
"allOf": [
{
"minContains": 1,
"maxContains": 1,
"contains": {
"$ref": "#/definitions/claim"
}
}
]
}
},
"required": [
"claim",
"commonFunctional"
]
}The example above shows a simple structure of a commonFunctional and claim entities, both required, and some underlying nesting. From this example you can deduce the following:
- Both
claimandcommonFunctionalare required on the highest level of the message. - The entityType attribute is always mandatory under each entity (this cannot be changed in AOS and goes for all AFD-definitions).
- If you use the
partyentity of entityTypecounterparty, thefullNameandbirthDateattributes are both required. - If you use the
partyentity of entityTypewitness, thefullNameattribute is required. - Other attributes are optional, such as the
incidentDateattribute when using the (also optional)incidententity. - Both the
claimandcommonFunctionalentity may occur exactly once (minContains = 1 and maxContains = 1). - The (optional)
repairStatusattribute has a predefined codelist of allowed values, as defined in a separate JSON Schema included when exporting the AFD-definition in AOS.
Feedback
Powered by
Post your comment on this topic.