What is a schema?
A schema is a specification defining a message’s structural, data type and cardinality requirements. In other words, a schema specifies what a message looks like. A schema acts as a blueprint that determines how data is presented in a message. The use of a schema promotes the preparation of unambiguous specifications. In addition, a schema can be used to define messages regarding structures, entities and attributes. It brings order to entities and attributes in a given structure. It defines the organization of the entities, determines the order in which they appear, and shows their mutual relationships. In the case of attributes, the schema offers the option to provide specific characteristics such as linked codelists, option lists and data types. A schema can be used as a basis for automated checking of messages, databases and dialogues. For example: data types and codelists for attributes.
Schema as part of AFD-definition Standard
A schema is part of the AFD-definition Standard because it ensures that the developers and systems can build and validate data in a standardized way, reducing the probability of errors and confusion. The purpose of a schema is to exchange data between different parties consistently, based on agreements or standards. An AFD-definition schema contains the structure of the AFD entities and attributes with the mutual relationships and characteristics as included in message types (known as ‘Berichtsoorten’ in AFD 1.0) or in AFD structures (AFD 2.0). A schema is machine-readable and helps ensure a structured and reliable exchange of data between different systems.
Technical use schema specifications
The AFD-definition Standard provides a framework and tooling to record specifications and checks, as well as checks at data element level. The use of common techniques, like XML or JSON schemas, ensures that a financial product or service is put into production accurately and efficiently.
Automated processing in software
The use of schemas makes it no longer necessary to manually enter specifications for a product or service in the administration software. The schema indicates which data may appear in a certain structure in a message. Automated processing makes it faster and more accurate. Input errors no longer occur and this improves data quality.
Validation against the schema
Besides the possibility to include the data and structure in a schema, it is also possible to validate a number of data characteristics.
- Data types and format restrictions: in AFD 1.0, the data types and format restrictions are included in the data catalog. These cannot be changed and are automatically included in the XML Schema. In AFD 2.0, only the data types are included in the data catalog, not the format restrictions. This means that the length of an attribute or the number of decimal places can be included in the JSON Schema itself.
- Mandatory/Optional: the schema allows to define whether an entity or attribute is mandatory or optional.
- Value restrictions: at attribute level it is possible to add, for example, an option list or value range. The data in the message must meet the value restrictions in the schema.
XML Schema (AFD 1.0)
The AFD-definition Standard uses XML schema to validate AFD 1.0 messages. This is a technique standardized by the World Wide Web Consortium (W3C) to validate XML messages.
XML (eXtensible Markup Language) is a markup language for encoding documents. The World Wide Web Consortium (W3C) has developed XML Schema, a specification for expressing the structure and constraining the contents of XML documents (messages). XML Schema Definition Language (XSD) is the main language for XML Schema definition, providing a standardized and formalized way to define the elements, attributes, and data types within an XML document.
More information is available at W3C Reference: [XML Schema Definition Language (XSD) 1.1](https://www.w3.org/TR/xmlschema11-1/)
XML Schema enables the creation of robust, self-describing XML documents by defining the valid structure and data types. This facilitates data exchange and interoperability by ensuring a common understanding of the data format among different systems and applications.
JSON Schema (AFD 2.0)
The AFD-definition Standard uses JSON Schema to validate AFD 2.0 messages. This is a technique standardized by the World Wide Web Consortium (W3C) to validate JSON messages.
JSON (JavaScript Object Notation) serves as a lightweight and human-readable data interchange format. The W3C has also developed JSON Schema to describe the structure and impose constraints on JSON data. JSON Schema provides a standardized method for specifying the expected structure, data types, and validation rules for JSON documents.
More information is available at W3C Reference: [JSON Schema Core](https://www.w3.org/TR/vc-json-schema/)
JSON Schema enhances the reliability and interoperability of JSON data by enabling developers to define a formal schema that can be used to validate and ensure the consistency of JSON documents. This contributes to more robust data exchange and integration across diverse systems and platforms.
Rules for applying XML Schemas (AFD 1.0)
The AFD-definition Standard follows the generic rules for the composition of XML Schemas. XML Schemas are quite extensive and provide a wide range of capabilities for defining complex structures, data types, constraints, basic dependencies, arrays and various other object properties. XML Schema also extensively supports annotations, namespaces and built-in documentation features. The following AFD guidelines apply for the composition of XML Schemas.
The table below shows the reference rules in the header of an XML Schema.
| Name | Description |
| version and encoding | In the basic element of XML Schema XML version 1.0 and UTF-8 encoding should be used. Use of XML version 1.1 or DTD is not allowed in AFD-definition Standard |
| namespace | Each AFD XML Schema needs a namespace. Namespaces group and organize elements and attributes to avoid conflicts between similar element names In AFD-definition Standard it is not allowed to use noNamespace. |
| prefixes | Default namespace prefixes are mandatory in AFD-definition Standard. The following prefixes are reserved for use by SIVI: cl (Codelist), fm (Format), ca (Codelist Actual). These prefixes are part of the standard XSD templates and cannot be used by other parties. |
| elementFormDefault | qualified – elements and attributes are in the targetNamespace of the schema |
| attributeFormDefault | unqualified – elements and attributes do not have a namespace |
Example reference rules XML Schema
This example shows the elements as discussed in the table above.
<?xml version="1.0" encoding="utf-8"?>
xsd:schema xmlns:xsd=“http://www.w3.org/2001/XMLSchema”
xmlns=“http://www.sivi.org/berichtschema” xmlns:fm=“http://schemas.sivi.org/
afdFormats” xmlns:cl=“http://schemas.sivi.org/afdCodelists”
targetNamespace=“http://www.sivi.org/berichtschema” elementFormDefault=“qualified”
attributeFormDefault=“unqualified”>
It is possible to add comments to a schema. This can be a remark or a supporting text.
| Name | Description |
| annotation | Documentation and Appinfo are both allowed to provide additional explanation. |
Example: annotation as part of an AFD-definition
The example below shows the use of annotation and specifcally appinfo and documentation.
Annotation can be used to give additional explanation of the message. In this example the appinfo explains, this AFD-definition is certified is and gives some extra information about the certification of this AFD-definition (like the HashCode, the timestamp of certification (TimeStampCertificering, the name of the schema (NaamSchema)).
The documentation gives general information about this AFD-definition, usually available in a commonFunctional.
...
<xsd:annotation>
<xsd:appinfo>
<SiviCertificeringsInfo xmlns="">
<Organisatie>SIVI</Organisatie>
<SIVICommunity>AFD</SIVICommunity>
<Berichtsoort>Contractdocument</Berichtsoort>
<Domein>Sandbox Motorrijtuigen</Domein>
<HashCode>7551737FB470719D1D3826484DF7D274115340C4</HashCode>
<DatacatVersion/>
<TimestampCertificering>2024-02-15T17:45:27</TimestampCertificering>
<NaamSchema>021-Q001-Goed op weg-001.00-nieuwePolis_aanroep</NaamSchema>
</SiviCertificeringsInfo>
</xsd:appinfo>
<xsd:documentation>
<documentDetails xmlns="">
<commonFunctional>
<tag/>
<businessLine>021</businessLine>
<porCompanyCode>Q001</porCompanyCode>
<productSegment/>
<productName>Goed op weg</productName>
<startDate>20240101</startDate>
<endDate/>
<dataCatalogVersion>42B</dataCatalogVersion>
<definitionVersion>001.00</definitionVersion>
<functionDescription>nieuwePolis_aanroep</functionDescription>
<changelog/>
</commonFunctional>
</documentDetails>
</xsd:documentation>
</xsd:annotation>
...The use of XSD elements in the AFD-definition Standard
In XML Schema for the AFD-definition Standard SIVI uses the following XSD elements.
| Name | Description |
| complexType | Entities in the AFD standard are always constructed as xsd:complexTypes with a nested child element “xsd:elements” in the XML Schema. |
| simpleType | Defines a simple type and specifies the constraints and information about the values of attributes or text-only elements |
| enumeration | Defines a list of acceptable values |
Examples: use of XSD elements
The example below shows the limitation of the payment term in months to monthly (value = 1 month), quarterly (value = 3), semiannually (value = 6) and annually (value = 12).
...
<xsd:simpleType>
<xsd:annotation>
<xsd:documentation>Betaaltermijn in maanden</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="fm:Numeriek3">
<xsd:enumeration value="1"/>
<xsd:enumeration value="3"/>
<xsd:enumeration value="6"/>
<xsd:enumeration value="12"/>
</xsd:restriction>
</xsd:simpleType>The example below shows the limitation of the codelist ADNDEK (Coverage type) to one value (2001, third-party liability).
...
<xsd:simpleType>
<xsd:restriction base="cl:ADNDEK">
<xsd:enumeration value="2001"/>
<xsd:annotation>
<xsd:documentation>Wettelijke Aansprakelijkheid</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
...Date and time types
| Name | Description |
| Date and time | The xsd Date Types cannot be used for the composition of an XML Schema for AFD-definition Standard. AFD 1.0 uses the date/time notation CCYYMMDD. That is different from the general notation in XML: CCYY-MM-DD |
What specifications are possible with XML Schema?
A schema supports unambiguous specifications. The specifications are made on two levels: entities and attributes. The applicable specifications are shown in the table below.
| Entity/attribute level | Specification description |
| Entity | Specify what entities exist in a product or service. |
| Entity | Specify which of them are mandatory. |
| Entity | Specify how many times entities may occur in a message. |
| Attribute | Specify what attributes exist in a product or service. |
| Attribute | Specify which of them are mandatory on the level of functions. |
| Attribute | Define a custom description if the description in the AFD-datacatalog does not meet the definition needed for the product or service. |
| Attribute with attached codelist | Specify value limitations by limiting the codes of a codelist. |
| Attribute with attached codelist | Specify the possibility to follow the actual codelist. |
| Attribute | Specify value limitations by limited value range (minimum value, maximum value). |
| Attribute | Specify value limitations by a custom option list. |
Rules for applying JSON Schemas (AFD 2.0)
The AFD-definition Standard follows the generic rules for the composition of JSON Schemas. JSON Schema provides natural integration with JavaScript and modern web technologies, and, thanks to a more natural syntaxis than XML Schema, is somewhat easier to read and work with than XML Schema. The following AFD guidelines apply for the composition of Schemas.
Contrary to XML Schema, namespaces do not exist in JSON Schema. All (element) names must be unique within the schema. Each schema starts with an opening tag (opening curly bracket: ‘{‘) $schema-tag and a description-tag. The table below contains the rules applying to AFD 2.0 (JSON Schema).
| Name‘ | Description |
| opening curly bracket ‘{‘ | On the highest level, each JSON Schema starts with an opening curly bracket. Contrary to XML and XML Schema, there is no ‘tag’ on the highest level of the JSON Schema |
| $schema (http://json-schema.org/draft-07/schema#) | Used for the version of the JSON Schema. Because of the general use in the market at this moment we use an ‘older version’ than the most recent one (draft 2020-12) |
| description | The description of the current schema |
Below an example of the first few rules of a JSON Schema is shown.
Example reference rules JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "JSON Schema SIVI 2.0",What specifications are possible with JSON Schema?
A schema supports unambiguous specifications. The specifications are made on two levels: entities (including entityTypes) and attributes. The applicable specifications are shown in the table below.
| Entity/attribute level | Specification description |
| Entity | Specify what entities exist in a product or service. |
| Entity | Specify which of them are mandatory. |
| Entity | Specify how many times entities may occur in a message. |
| Attribute | Specify what attributes exist in a product or service. |
| Attribute | Specify which of them are mandatory on the level of functions. |
| Attribute | Define a custom description if the description in the AFD-datacatalog does not meet the definition needed for the product or service. |
| Attribute with attached codelist | Specify value limitations by limiting the codes of a codelist. |
| Attribute with attached codelist | Specify the possibility to follow the actual codelist. |
| Attribute | Specify value limitations by limited value range (minimum value, maximum value). |
| Attribute | Specify value limitations by a custom option list. |
| Attribute | Specify the possibility to define that an attribute is ‘greater than’ a certain value instead of ‘greater/equal’ (by excluding the defined minimum value). Only AFD 2.0. |
| Attribute | Specifiy the possibility to define that an attribute is ‘less than’ a certain value instead of ‘less/equal’ (by excluding the defined maximum value) Only AFD 2.0. |
| Attribute | Specify the multiplicity of a numeric value. It is possible to define the number of decimal places, but also the factor in which a number may appear. For example: 0.00001 indicates that input contains 5 decimal places. 0.5 indicates that input increases by 0.5 (0.5, 1.0, 1.5). Only AFD 2.0. |
Post your comment on this topic.