You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.
The domain schema is a contract of communication. The purpose of the domain schema is to define what items are needed in a message and to specify its elements. For example the representation of a person. In this case the persons first name (1), always followed by his last name and his job(s). The right column represents the application domain, where the left column represents the domain schema of the message.
You start with an entity (2) that represents the begin and the end of the message. For every attribute/relation you can select a name (3), what datatype (4) it is, if it is required (5) to be part of the message, if it is multivalued (6), add a validation (7), and any additional documentation (8) that will be part of the OpenAPI feed.
- When you add the right column of the domain schema first, the left column will be prefilled with a copy of the name from the right column. When editing the left column then it is "user-set" and the automatic copy function will be disabled.
- When an attribute or relation is selected, the fields on the right side of the screen are prefilled using the information of the attribute or relation. You may deviate from this chosen setting.
- The validations in the domain schema can only be a validation type. Validation rules should be added to the corresponding attribute.
- When optional elements of the messages are left out, the parser will set the value unknown for them. This is the same for NULL values in JSON.
- When generating a JSON message, unknown values will be mapped to NULL. However, the element will be left out completely when the attribute is not required and the value is not user-set.
A domain schema is case sensitive. The attribute in the right-hand column typically contains one or more uppercase characters (the use of CamelCase is a modeling guideline). This is copied to the left-hand column as a suggestion for the incoming attribute name. If the incoming response has the same attribute name, but not the exact same casing, this attribute is not found in the domain schema and the mapping won't work. This can be a problem that is easily overlooked.
You can make translations between message and your application domain. For example, it is possible to store a single-valued attribute in the message in a multi-valued attribute in your application domain. You have to be aware that you can only make a translation into a more general data type. For example the other way is not possible. When sending a message, it is not possible to place a multivalued attribute of your application domain in a single valued attribute of the domain schema.
Hide root element
To define an unnamed array the 'Hide root element' checkbox corresponding to the domain schema root element must be ticked.
Example of a JSON message that consists of an unnamed array:
[
{
"Id": 1,
"Name": "Bob",
"Age": 35,
"Gender": "male"
}
]
When making use of unnamed arrays, only one child (relation or attribute) can follow the root element.
Domain Schema in another Domain Schema
If parts of the domain schema are being reused, or the size of the domain schema is getting too large to understand and/or maintain, it may be a good choice to cut up the large domain schema and use the sub domain schema's in the main domain schema.
Applying a sub-domain schema is only possible if the following rules apply:
- a sub-domain schema can be added under the root entity or under a relation,
- the root entity of the sub-domain schema should be the target entity of the selected relation,
- the root entity of the sub-domain schema should have as base entity the target entity of the selected relation,
- adding a sub-schema which has root element hidden will trigger a validation message.
Because domain schemas can be referenced by other domain schemas, it is possible to create infinite loops. For more information on how to set the infinite-loop-limit for Runtime, check the properties documentation page.
Infinite loop
Because domain schemas can be referenced by other domain schemas, it is now possible that infinite loops are created.
For preview purposes, a hardcoded limit of 2 loops was set for the preview.
For more information on how to set the infinite-loop-limit for Runtime, check the properties documentation page.
Overview
Content Tools