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.

Function example

Below is a (simplified) example JSON Schema for the calculatePremium function (see also the calculatePremium chapter), with commonFunctional and policy both required within the policyStructure (on the highest level). This example also shows mandatory attributes depending on the entityType: in this example, businessLine and contractNumber (among others) are mandatory when using policyDetails as entityType for the policy entity.

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"description": "Example schema for calculatePremium request function",
	"title": "policyStructure",
	"type": "object",
	"required": [
		"commonFunctional",
		"policy"
	],
	"properties": {
		"commonFunctional": {
			"type": "array",
			"allOf": [
				{
					"contains": {
						"$ref": "#/definitions/commonFunctional"
					},
					"minContains": 1,
					"maxContains": 1
				}
			]
		},
		"policy": {
			"type": "array",
			"uniqueItems": true,
			"allOf": [
				{
					"contains": {
						"$ref": "#/definitions/policyDetails"
					},
					"minContains": 1,
					"maxContains": 1
				}
			]
		},
		"party": {
			"type": "array",
			"allOf": [
				{
					"contains": {
						"$ref": "#/definitions/regularDriver"
					},
					"minContains": 0,
					"maxContains": 1
				},
				{
					"contains": {
						"$ref": "#/definitions/policyHolder"
					},
					"minContains": 0,
					"maxContains": 1
				}
			]
		}
	},
	"definitions": {
		"commonFunctional": {
			"type": "object",
			"properties": {
				"function": {
					"$ref": "codelists.json#/definitions/ADNFUN"
				},
				"dataCatalogVersion": {
					"$ref": "codelists.json#/definitions/ADNAFM"
				},
				"statusDescription": {
					"type": "string"
				}
			},
			"required": [
				"function",
				"dataCatalogVersion"
			],
			"additionalProperties": false
		},
		"policyDetails": {
			"type": "object",
			"required": [
				"entityType",
				"businessLine",
				"porCompany",
				"afdDefinitionName",
				"afdDefinitionVersion"
			],
			"properties": {
				"entityType": {
					"const": "policyDetails"
				},
				"businessLine": {
					"type": "string"
				},
				"porCompany": {
					"$ref": "codelists.json#/definitions/PORMAA"
				},
				"afdDefinitionName": {
					"type": "string"
				},
				"afdDefinitionVersion": {
					"type": "string"
				}
			},
			"additionalProperties": false
		},
		"regularDriver": {
			"type": "object",
			"required": [
				"entityType",
				"birthDate"
			],
			"properties": {
				"entityType": {
					"const": "regularDriver"
				},
				"birthDate": {
					"format": "date"
				}
			},
			"additionalProperties": false
		},
		"policyHolder": {
			"type": "object",
			"required": [
				"entityType",
				"birthDate"
			],
			"properties": {
				"entityType": {
					"const": "policyHolder"
				},
				"birthDate": {
					"format": "date"
				}
			},
			"additionalProperties": false
		}
	}
}

AFD-definition

The following is an example of an AFD-definition in JSON Schema for a policy entity. Restrictions have been specified for the contractNumber, effectiveDate, contractDurationInMonths and externalIndicative attributes. In this example, effectiveDate must be of JSON format date and contractNumber can contain up to 30 characters. In addition, contractyNumber or externalIndicative must always be filled; this is enforced with the anyOf element in JSON Schema.

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"title": "policy",
	"description": "Legal document issued to the insured setting out the terms of the contract of insurance.",
	"type": "object",
	"oneOf": [ {
		"properties": {
			"contractNumber": {
				"description": "The identifying characteristic that a company (or underwriting agent) assigns to the policy.",
				"type": "string",
				"minLength": 1,
				"maxLength": 30
			},
			"effectiveDate": {
				"description": "Date on which the data of this entity takes/took effect.",
				"type": "string",
				"format": "date"
			},
			"contractDurationInMonths": {
				"description": "Duration of the contract in months.",
				"type": "integer",
				"exclusiveMinimum": 0,
				"maximum": 120
			}
		},
		"additionalProperties":false, 
		"required": [ "contractNumber" ]
	},
	{
		"properties": {
			"externalIndicative": {
				"description": "The identifying characteristic that an intermediary assigns. Can also be used as a temporary contract number.",
				"type": "string",
				"minLength": 1,
				"maxLength": 30
			},
			"effectiveDate": {
				"description": "Date on which the data of this entity takes/took effect.",
				"type": "string",
				"format": "date"
			},
			"contractDurationInMonths": {
				"description": "Duration of the contract in months.",
				"type": "integer",
				"exclusiveMinimum": 0,
				"maximum": 120
			}
		},
		"additionalProperties":false, 
		"required": [ "externalIndicative" ]
	} ]
}

Example JSON message that complies with the Schema above

{
		"contractNumber" : "1351312jfa",
		"effectiveDate" : "2020-04-01"
}

Example JSON message that does not comply with the Schema above, and the resulting error message

{
		"contractDurationInMonths" : 5,
		"effectiveDate" : "2020-04-01"
}
'oneOf': Expected 1 schemas to match, but only 0 did match.
		Reason: the following schemas did not match (see below)
			/oneOf/0
			/oneOf/1
	Mandatory property 'contractNumber', stipulated by schema property 'required', is missing.
	Mandatory property 'externalIndicative', stipulated by schema property 'required', is missing.

Feedback

Thanks for your feedback.

Post your comment on this topic.

Post Comment