2.7. Non-AFD segments within an AFD message

SIVI AFS is a demand-driven standard. Parties can request labels, codes, and functions that are not yet part of the standard. SIVI applies the principle that parties “functionally get what they ask for.” This means that sometimes SIVI provides a different technical solution or point to an existing attribute that can be used to model the desired outcome.
Sometimes parties want to add data-elements to an AFD message that are so organization-specific that adding them to the AFD is not suitable: after all, there is no general purpose for standardizing such a label. Examples are specific fields that are unique to an organization and have no general meaning to the industry. Therefore, these fields do not belong in the AFD but they do require a method to be exchanged or recorded using AFD messages. This chapter shows how to model such non-AFD data within AFD messages. SIVI offers two possible solutions to achieve this.

Two possible solutions in AFD 2.0: noAFD and anyJSON

The entity customEntity contains the entityTypes noAFD and anyJSON.

• noAFD is used when validation on the content of the entity is required. Here you can put JSON about which you do want to make specifications, but which does not appear in the AFD.
• anyJSON is used when validation on the entity content is not required. Here, ‘any JSON specification you want’ can be included.

Use of non-AFD data-elements within AFD message with validation

The entityType noAFD is used when validation applies to the content of the entity. Here you can store JSON code for which you do want to set up specifications, but which is not part of AFD.

Below, an example for the entityType noAFD is presented. The accompanying schema also includes validation rules for the fields within this entity. We will elaborate on this further towards the end of this chapter. In this example, you see an AFD message in JSON format with a commonFunctional and policy entity at the highest level. Nested under the policy, there are coverage and object entities, as usual. Nested under object, it is possible to insert a non-AFD segment: the customEntity entity with entityType noAFD is used here. The rest of the attributes are custom-defined non-AFD elements: in this example, they are InterneCodeVoertuig, InterneAfdeling, VoertuigGezien, and Voertuigklasse.

{
	"commonFunctional": [
		{
			"entityType": "default",
			"dataCatalogVersion": "42D"
		}
	],
	"policy": [
		{
			"entityType": "policyDetails",
			"businessLine": "020",
			"expiryDate": "2025-03-01",
			"contractNumber": "fnk12098lkj",
			"coverage": [
				{
					"entityType": "hullVehicle",
					"coverageCode": "2008",
					"commercialName": "Casco Plus Ultra"
				}
			],
			"object": [
				{
					"entityType": "motorVehicle",
					"newValue": 24000,
					"constructionYear": 2009,
					"firstOwner": true,
					"customEntity": [
						{
							"entityType": "noAFD",
							"InterneCodeVoertuig": "80k",
							"InterneAfdeling": "Auto1",
							"VoertuigGezien": false,
							"Voertuigklasse": "7K"
						}
]}]}]}

Use of non-AFD without validation

If you replace the entityType noAFD with anyJSON in the example above, the entire message will contain JSON code, but no validation will take place within the customEntity entity. The advantage is that the entire message can be processed as a JSON message. The starting point here is that parties use correct JSON syntax.

{
	"commonFunctional": [
		{
			"entityType": "default",
			"dataCatalogVersion": "42D"
		}
	],
	"policy": [
		{
			"entityType": "policyDetails",
			"businessLine": "020",
			"expiryDate": "2025-03-01",
			"contractNumber": "fnk12098lkj",
			"coverage": [
				{
					"entityType": "hullVehicle",
					"coverageCode": "2008",
					"commercialName": "Casco Plus Ultra"
				}
			],
			"object": [
				{
					"entityType": "motorVehicle",
					"newValue": 24000,
					"constructionYear": 2009,
					"firstOwner": true,
					"customEntity": [
						{
							"entityType": "anyJSON",
							"xmlBlob":  "<entityType>noAFD</entityType><InterneCodeVoertuig>80k</InterneCodeVoertuig><InterneAfdeling>Auto1</InterneAfdeling><VoertuigGezien>false</VoertuigGezien><Voertuigklasse>7K</Voertuigklasse>"						}
]}]}]}

Use of random code within an AFD 2.0 message

The two examples above show how to use JSON fields that are not in the AFD within an AFD 2.0 message. Sometimes it can also be desirable to include ‘foreign’ code in a message other than JSON, such as Edifact or XML. This can be done by means of a ‘blob’. Blobs are not validated based on their content, so the entityType anyJSON is always used for blobs. Please note that the content of the customEntity must still be valid JSON syntax: you achieve this by passing the blob as a value to an attribute.

In this example, the same data appear as in the previous example, but now as an XML message (as a blob) as the value of the attribute xmlBlob. (Because there is no validation on the content within the anyJSON entityType, it does not matter what the name of the attribute is.)
As long as the content of the blob complies with the JSON standard, by taking escape characters into account, you can use this method to provide message content in a different language, such as Edifact or XML.

Validation and AOS

The approach for using non-AFD segments within AFD messages, as described here, also requires adjustments to AFD-definitions:

• For noAFD you must be able to create your own JSON Schema specifications for the content of the customEntity.
• For anyJSON, validation ‘stops’ at the level of the customEntity entity: it must still be in the correct place in the structure, but the content of the entity is not validated.
  

For the online SIVI environment AOS, this means that in a future release it will be possible to ‘inject’ JSON Schema specifications into the correct place in the AFD-definition using snippets. (This is already possible for combination products in AFD 1.0.)

Agreements are responsibility of the parties

Parties using the customEntity method must make agreements with processing parties on how to process these messages. After all, the content of these entities does not contain standardized AFD labels.

Is it sensible to use non-AFD-segments?

The starting point is that messages follow the entire AFD where possible. This allows us as a sector to exchange data efficiently and at reasonable costs. At the same time, we as a sector do not benefit from the creation of large collections of exotic entities and attributes within the AFD. The scenario of ‘no AFD message then’ is also not a valid option. With the non-AFD segment, we meet an explicit market demand. At the same time, we assume that this will be used very cautiously and appropriately. If have any doubts, do not hesitate to consult with us about the use. SIVI will monitor incorrect use where possible and handle complaints about this.