Message Validation
The rule command object can be used to establish validation constraints that facilitate the verification of message structure and content. Rule objects require a kind descriptor consisting of alphanumeric characters and must conclude with an ends closure directive.
In the example shown below, a local rule named "myrule" is defined. This rule contains a single item named "total" with the expected data type of decimal. The once occurance constraint decorator means that there must be only one occurance of the item "total" within the immediate body of the message.
rule myrule
item total decimal once
ends
To apply the rule against an info object, the uses header directive is specified. In the example shown below, the info object would successfully pass validation because the value given for “total” is decimal, and the item appears only once.
info mymessage
uses rule myrule
item total as 12.62
ends
Local rules persist within the memory of the active instance of the CXIO Engine. To remove the rule from memory, use the following command:
drop rule myrule
Internet Rules
Rules can be fetched and applied from the internet using http or https protocols using the following syntax, as shown below.
info mymessage
uses rule https://rules.centrifax.com/example/myrule.cxio
item total as 12.62
ends
Validating Lines and Items
Individual message lines and items can be validated using rules. In the example shown below, a line named “orderline” is defined with a rule called “myorderrule”. The line has a many decorator, meaning that there should be at least one occurrence of “orderline”.
Within the order line, items “sku”, “qty” and “price” must appear only once with the appropriate data type. The “note” does not need to be provided, but if specified should be of type string.
rule myorderrule
line orderline many
item sku string once
item qty int once
item price decimal once
item comment string none
ends
ends
info myorder
uses rule myorderrule
line orderline
sku: "000001"
qty: 12
price: 34.52
ends
line orderline
sku: "000002"
qty: 12
price: 7.15
comment: "Only current season."
ends
ends
drop rule myorderrule
Applying Multiple Rules
It is possible to apply more than one rule to the same message, as shown in the example below. When applying multiple rules, the message will only pass validation if all rules are successfully tested.
/* Define the first rule */
rule my_rule1
item total decimal once
ends
/* Define the second rule */
rule my_rule2
item currency char(3) once
ends
/* The message */
info my_message
uses rule my_rule1
uses rule my_rule2
total: 12.62
currency: “GBP”
ends
/* Drop the rules */
drop rule my_rule1
drop rule my_rule2
Occurance Constraints
There are three types of occurrence constraints which are none, once and many.
| None | The item does not need to be specified, but if provided it must agree with any specified data type. Where no occurrence constraint decorator is given within a rule, this is the default. |
|---|---|
| Once | The item can only be occur once. |
| Many | The item must occur at least once. There is no upper limit on number of occurances. |
| Many (max) | The item must occur at least once, however cannot occur more than the specified maximum times. Items must agree with any specified data type. |
| Many (min, max) | The item must occur at least the minimum number times specified, and cannot occur more than the maximum times specified. |
In the example below, the rule "my_occurance_rule", defines an item named "test" with a min and max occurance count of 2. The below will pass validation because there are exactly two occurances of test and no explicit data type was specified within the rule.
rule my_occurance_rule
item test many(2,2)
ends
info my_occurance_info
uses rule my_occurance_rule
test: "hello"
test: 123
ends
Enumeration Constraints
Enumerations define sets of available values and can be used within rules to restrict the value given.
In the example below, the rule "my_enum_rule" has an enum named "my_vals" containing three possible values: "R1", "X3", "P7". An item named "test" with an occurance constraint of once, references the "my_vals" enum with the in decorator.
The case directive with strict means that both item names and values are sensitive.
rule my_enum_rule
case strict
enum my_vals
"R1",
"X3",
"P7"
ends
item test once in my_vals
ends
info my_enum_info
uses rule my_enum_rule
test: "X3"
ends