9.1. JSON

Introduction

JSON is the abbreviation for JavaScript Object Notation. JSON is a syntax used in computer programming for using data in a structured way. JSON is a platform independent, open-standard syntax. Specific open standards such as JSON Schema and AJAX have been developed based on JSON. API development that is based on the REST architecture uses the JSON syntax to specify API functions. API webservices can still use other payload syntaxes, however, like XML for example.

AFD in JSON

Entities and attributes

In JSON, AFD entities are always explicitly defined with a tag, for example "party", "policy" or "financialTransaction". The only exception in JSON is that the entity on the highest level of the message and/or structure remains implicit (see example below). Attributes are nested under their respective entities and also explicitly defined as a JSON tag. For example "contractNumber", "dataCatalogVersion" or "surname". The filled value of an AFD attribute in JSON is always placed after the attribute tag and a colon, and placed between quotation marks when not a number or boolean. For example "policyNumber": "1234567GH" or "startDate": "2017-01-24", but "numberOfHullClaims": 3, "totalLossAmount": 231.42 and "excessAmountLoss": true.

Order of entities and attributes

The order of entities in a JSON message is free. The only exception is that AFD messages must always start with the commonFunctional and commonTechnical entities. If a JSON Schema is used, the order of the entities must comply with the definitions within the JSON Schema. The same applies to attributes: the order can be chosen freely, unless the corresponding JSON Schema prescribes an order.

Arrays

JSON allows the use of arrays: a listing/repetition of the same entity. This is done in JSON with square brackets, without naming the entity itself more than once. See the example at the bottom of this page, where party occurs twice: once with entityType insuredPerson, and the second time as policyHolder. Note that all entities in AFD 2.0 are an array, even if there is only one instance of that entity.

Encoding

UTF-8 is the default character encoding for JSON documents. AFD also applies this standard: no limited character set applies.

Example

{
	"commonFunctional": [ {
		"entityType": "default",
		"function": "15",
		"dataCatalogVersion": "99Z"
	} ],
	"policy": [ {
		"entityType": "policyDetails",
		"porCompany": "M088",
		"contractNumber": "P20190101-010",
		"party": [ {
			"entityType": "insuredPerson",
			"refKey": "R918273645",
			"surname": "Jansen",
			"initials": "R.I.O."
		},
			"entityType": "policyHolder",
			"refKey": "R6930129",
			"surname": "de Vries",
			"initials": "B.D.G."
		} ],
		"object": [ {
			"entityType": "vehicle",
			"refKey": "SIVI20",
			"licensePlate": "SI-VI-20",
			"objectType": "00050"
		} ]
	} ]
}

JSON Schema

JSON Schema is a JSON derived language which allows users to annotate and validate JSON documents. It can be used to describe existing data formats, provide clear human- and machine-readable documentation, and validate data in order to both facilitate automated testing and ensure the quality of client submitted data. Within the context of SIVI 2.0, JSON Schema is used as main validation language in the AFD-definition Standard. More information about JSON Schema in general can be found on the website of JSON Schema.