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. It is the definition of the interface between the REST message (JSON or XML, left column) and the application model (Blueriq profile, right column).
Example
For example, the representation of a person:
In this case the person’s 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.
A domain schema always starts with a root entity that is referred to via a 1:1 body relation in the REST service. The root entity's name is used as a starting point and only relevant for an XML-message (2). For every attribute/relation you can select a name (3), what data type (4) it is, if it is required (5) to be part of the message, if it can be null (6), if it is multivalued (7), add a validation (9), and any additional documentation (8) that will be part of the OpenAPI feed.
JSON preview
During editing, it is possible to preview the message in JSON format. This preview is kept in sync with the model. The JSON preview can be found in the bottom drawer. XML preview support is not available in Encore.
Properties
| Property | Type | Description |
|---|---|---|
| Hide root element | Root entity | Tick this box if you want your message to start with an unnamed array; that is square bracket ([) instead of a curly bracket ({) in JSON. In this case, only one child (relation or attribute) can follow the root element. |
| Schema data type | Attribute | The data type of the item in the JSON or XML message. This value should correspond with the data type of the attribute. This property is copied from the attribute when added to the domain schema. |
| Schema name | All | The schema name is the name of the item in the JSON or XML message. If you add the right column first, the left column will automatically sync, unless the left column has been manually changed and no longer matches the name in the right column. Unlike names of elements in Blueriq, schema names are case-sensitive. |
| Required | Attribute, relation, domain schema | When enabled, the item is required to be part of the message. It may however still be an empty string, or |
| Nullable | Attribute, relation, domain schema | When enabled, an incoming |
| Multivalued | Attribute, relation, domain schema | Determines whether the item can be multivalued. This will insert square brackets in the JSON message. This property is copied from the attribute or relation when added to the domain schema. 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. 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. |
Item name | Multivalued attribute, relation, domain schema | Item names are used for XML messages to create names for items within arrays. For example: if the array is named 'Airports' and the Item Name 'Airport' the XML would be Item names are ignored for JSON messages. |
| OpenAPI description | Attribute, relation | Provides documentation for external consumers of a Blueriq API in the OpenAPI feed. |
| Validation | Attribute | One or more validation types can be selected here to validate incoming data. Only incoming requests and incoming responses are validated. For incoming requests to be validated, "Validate requests" should be checked in the web service. Validation rules should be added to the corresponding attribute. |
| Reusable domain schema name | Relation | 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 schemas in the main domain schema. Because domain schemas can be referenced by other domain schemas, it is possible to create an infinite loop. Click here for more information on how to set the infinite-loop-limit in the Runtime. |
Schema elements
Schema elements can be used to expose data that is not captured in the profile, such as a justification tree. Read more about using justifications trees in a domain schema here.
Dealing with the value null
In REST messages, the value null may occur, but this value does not exist in a Blueriq profile. null can have different meanings; it can be absent or unknown and being explicit or implicit. Blueriq interprets null as an explicit absent value and therefore parses it as a 'user set unknown' in the profile. This is the closest match that can be made but not always correct, since unknown in Blueriq indicates that the value can not be conclusively determined with the given knowledge.
'User set unknown' values are losing its source type after a data mapping, where unknown attributes of any source type are cleared as the source type is ignored due to the use of an expression.
Overview
Content Tools