Context and motivation

Defining hierarchies makes it possible to distinguish and record different levels or groups of code values within codelists. Hierarchies are defined in separate JSON files. By using JSON files, there is no impact on the flat structure of the codelists currently included in the AFD data catalog.

Need for details

Values in AFD codelists do not always supply the level of detail individual parties or processes require. While some parties or processes can handle a global level, others require a very detailed level.

An example of this is the codelist ADNBRZ (profession of self-employed). Sometimes the classification doctor suffices, but for other parties the specific profession surgeon or even neurosurgeon is relevant. This requires a method to model the relationship between data within a codelist.

Additional standard

SIVI has developed a standard for hierarchies within AFD codelists. This machine-readable standard is only applied to codelists in which a hierarchy is functionally desired. The standard is a technical addition to the relevant AFD codelists. The codelists retain their known flat structure of code value with description, but are supplied with a hierarchical table as a supplement.

The additional hierarchy table is supplied in the form of a JSON file in combination with the relevant codelist. Using this JSON file – the codelist hierarchy – it is possible to:

  1. look up the level of a relevant code value, and
  2. select the correct code value at the desired level for the relevant process.

The codelist hierarchy JSON can be easily converted to XML format if so desired.

JSON with nested structure

The codelist hierarchy JSON is composed of the following elements:

  • A root node (untitled in JSON).
  • A codelist element with the boolean externalCodelist (‘true’ or ‘false’).
  • A value element (value), description of the code value (nodeDescription), description of the hierarchical path (pathDescription), the screen name (displayName) and explanation (explanation). At the highest level these describe the name, description, screen name and explanation of the codelist, at lower levels that of code values.
  • Indication of the current level in the code list (codeValues).
  • Code values of the current level in the codelist (code).

Example

Levels are applied by nesting codeValues elements under the relevant codeValues element. The pathDescription element then successively contains the nodeDescriptions of the parent levels, separated by a “;”. See below example of (a shortened part of) the codelist hierarchy JSON of codelist ADN Branch code

{
"codelist": [
{
	"external": "N",
	"value": "ADNBRA",
	"nodeDescription": "ADN Branch code",
	"pathDescription": "ADN Branch code",
	"explanation": "Codelijst bevat AFD branchecodes",
	"codeValues": [
		{
		"code": [
			{
				"value": "010",
				"nodeDescription": "Ongevallen en ziekte",
				"pathDescription": "Ongevallen en ziekte",
				"displayName": "Ongevallen en ziekte",
				"explanation": "",
				"codeValues": [
					{
						"code": [
							{
							"value": "011",
							"nodeDescription": "Ongevallen",
							"pathDescription": "Ongevallen en ziekte;Ongevallen",
							"displayName": "Ongevallen",
							"explanation": ""
							},
							{
							"value": "012",
							"nodeDescription": "Ziektekosten",
							"pathDescription": "Ongevallen en ziekte;Ziektekosten",
							"displayName": "Ziektekosten",
							"explanation": ""
							}
						]
					}
				]
			},
			{
				"value": "020",
				"nodeDescription": "Motorrijtuigen",
				"pathDescription": "Motorrijtuigen",
				"displayName": "Motorrijtuigen",
				"explanation": "",
				"codeValues": [
					{
						"code": [
							{
							"value": "021",
							"nodeDescription": "Auto",
							"pathDescription": "Motorrijtuigen;Auto",
							"displayName": "Auto",
							"explanation": ""
							},
							{
							"value": "022",
							"nodeDescription": "Caravan",
							"pathDescription": "Motorrijtuigen;Caravan",
							"displayName": "Caravan",
							"explanation": ""
							},
							{
							"value": "023",
							"nodeDescription": "Bromfiets",
							"pathDescription": "Motorrijtuigen;Bromfiets",
							"displayName": "Bromfiets",
							"explanation": ""
							}
						]
					}
				]
			}
		]
}]}]}

In this example you see a (shortened) representation of the codelist ADN Branch code (ADNBRA). The values 011 and 012 are nested below 010, and the values 021, 022 and 023 are nested below 020. The values 020 and 010 are at the same level.

Added elements

Two new elements, explanation and displayName have been introduced. In addition to the existing description element (nodeDescription), the explanation element has been added. This element of type String allows for a more detailed explanation of the corresponding code.

Because code descriptions must be unique, the nodeDescription can contain the full hierarchical path. In order to be able to display a logical name on a screen, the displayName element is included. This contains the exact description of a code value without the parent path in the hierarchy.

Functions

To run through a codelist hierarchy, two functions are needed:

  • Descending from the start (root) into the hierarchy (look-down).
  • Move up from a point in the hierarchy to the root (look-up).

For both functions, SIVI has developed code in Java that will soon be available on the SIVI website.

Look-down

With look-down, a user can walk through the hierarchical structure of the codelist. This allows a user to easily select the correct code value at the desired level for the relevant process in large codelists. A user can navigate step by step through the codelist and does not have to search through a list of (for example) 80 code values.

lookdown is set up as a java class and can be called with the getChildren function. The function requires two parameters: the location of the codelist hierarchy JSON and the given code value (both as String). The function returns a list of the code values of all direct child nodes (as String) of the given code value.

Please note: this list only contains the code values, so no descriptions, paths and/or explanations. This has been chosen to facilitate the machine-machine use of this functionality.

An example with (a simplified version of) the ADNBRA codelist, with the code value 020 as parameter, returns all child nodes of 020:

> lookdown.getChildren(ADNBRA, 020)
> [021, 022, 023, 024, 025, 026, 027]

An example with (a simplified version of) the ADNBRA codelist, with the root node ADNBRA as parameter, returns all root nodes of the codelist:

> lookdown.getChildren(ADNBRA, "ADNBRA")
> [010, 020, 030, 040, 050, 060, 070, 080, 090, 100, 600, 700, 990, 991, 992, 999]

Look-up

With look-up, a user can retrieve the description of a code and the location in the hierarchy. This allows the code to be linked to a code at a higher level. This allows, for example, comparison software to normalize input from different levels so that apples can be compared with apples (for example, dentist with dentist - pediatric dentist).

lookup is set up as a java class and can be called with the getPath function. The function requires two parameters: the location of the codelist hierarchy JSON and the given code value (both as String). The function returns a list of the code values from the path of the given code value, including the code value itself, up to and including the root node (the name of the codelist).

An example with (a simplified version of) the ADNBRA codelist, with code value 023 as parameter, returns the path from 023 to the root node:

> lookup.getPath(ADNBRA, 023)
> [023, 020, ADNBRA]

Feedback

Thanks for your feedback.

Post your comment on this topic.

Post Comment