IATI Ruleset Spec - JS Edition
An IATI Ruleset is a JSON document. The structure is described below.
This specification is used by the IATI Validator starting with version 2. See Validator API for more information on the programmatic use of the rules.
A JSON schema is available to test that the structure of a Ruleset is correct.
Each JSON document has the form:
{
"CONTEXT": {
"RULE_NAME": {
"cases": CASE_DICT_ARRAY
}
}
}
Where CONTEXT
is an xpath expression. This will be used to select the XML elements that the contained rules will be tested against.
RULE_NAME
is one of rule names listed belowCASE_DICT
is a dictionary where the contents depend onRULE_NAME
CASE_DICT_ARRAY
is an array of case dictionaries. The contents of each dictionary depend on theRULE_NAME
The possible keys in a case dictionary are:
condition
An xpath string
If this evaluates to False, the rule will be ignored
idCondition
If this evaluates to False, the rule will be ignored
NOT_EXISTING_ORG_ID - Checks that values in
paths
are NOT an existing Publisher Organisation ID from the RegistryNOT_EXISTING_ORG_ID_PREFIX - Checks that values in
paths
are NOT prefixed with an existing Publisher Organisation ID from the Registryeval
An xpath string
Can evaluate to True or False
paths
An array of xpath strings
These are evaluated to give a list of elements that the named rule then operates upon
less
A string containing the xpath of the smaller value (or older value when working with dates)
more
A string containing the xpath of the larger value (or more recent value when working with dates)
regex
A string containing a perl style regular expression
sum
A number that is the expected sum
excluded
An array of xpath strings
Evaluate which elements should not coexist with other elements
date
A string containing the xpath to a date
start
A string containing the xpath to a start date
end
A string containing the xpath to an end date
one
A string containing the xpath of something that must exist or
all
must be followedall
A string containing the condition that must be met for all elements if
one
is not metforeach
An xpath string to group the loop by and evalute each
do
with the substituted resultdo
An array of rules
To evaluate with
foreach
Available rules include:
strict_sum
,if_then
,atleast_one
,no_more_than_one
subs
An array of keys where the value matched in
foreach
should be substituded for the$1
values in thedo
casesprefix
An array of xpath strings
The matches of which, contain the possible prefixes for a path
If set to “ORG-ID-PREFIX” for startsWith, checks against provided list of prefixes in
idSets.ORG-ID-PREFIX
idSets
are passed to the Rule evaluation code
Rule Names
- Rule names are listed in bold
Keys: The keys for each rule are then listed. They are listed in snake-case/camel-case. The JS validator can handle either snake-case or camel-case.
Followed by a brief description of the rule’s function
- no_more_than_one/noMoreThanOne
Keys:
condition
,paths
There must be no more than one element described by the given paths
- atleast_one/atLeastOne
Keys:
condition
,paths
There must be at least one element described by the given paths
- only_one_of/onlyOneOf
Keys:
excluded
,paths
If there’s a match of the elements in
excluded
, there must not be any matches inpaths
, if there are no matches inexcluded
, there must be exactly one element frompaths
- one_or_all/oneOrAll
Keys:
one
,all
one
must exist otherwiseall
other attributes or elements must exist- dependent/NOT IMPLEMENTED IN JS
Keys:
condition
,paths
If one of the provided paths exists, they must all exist
- sum/sum
Keys:
condition
,paths
,sum
The numerical sum of the values of elements matched by
paths
must match the value for thesum
key- date_order/dateOrder
Keys:
condition
,less
,more
The date matched by
less
must not be after the date matched bymore
If they are equal, the are valid
If either of these dates is not found, the rule is ignored
- date_now/dateNow
Keys:
date
The
date
must not be after the current date- time_limit/timeLimit
Keys:
start
,end
The difference between the
start
date and theend
date must not be greater than a year- between_dates/betweenDates
Keys:
date
,start
,end
The
date
must be between thestart
andend
dates- regex_matches/regexMatches
Keys:
condition
,idCondition
,paths
,regex
The provided
regex
must match the text of all elements matched bypaths
idCondition
is also an optional parameter- regex_no_matches/regexNoMatches
Keys:
condition
,paths
,regex
The provided
regex
must match the text of none of the elements matched bypaths
- startswith/startsWith
Keys:
condition
,idCondition
,paths
,start
,separator
The text of each element matched by
paths
must start with the text of one of the elements matched byprefix
(or a list of prefixed provided inidSets
) with an optionalseparator
in betweenprefix
separator
pathMatchText
idCondition
is also an optional parameter- unique/unique
Keys:
condition
,paths
The text of each of the elements described by
paths
must be unique- if_then/ifThen
Keys:
condition
,cases
,if
,then
,paths
If the condition evaluated in
if
is true, thenthen
must resolve to true as wellpaths
can be defined to provide additional context data in the output if a rule fails, but had no bearing on the pass/fail of the rule- loop/loop
Keys:
foreach
,do
,cases
,subs
All elements in
foreach
are evaluated under the rules insidedo
- strict_sum/strictSum
Keys:
paths
,sum
The decimal sum of the values of elements matched by
paths
must match the value for thesum
key- no_spaces/noSpaces
Keys:
paths
The text of each of the elements described by
paths
should not start or end with spaces or newlines
Rule Example
{
"/iati-activities/iati-activity": {
"atleast_one": {
"cases": [
{
"paths": ["iati-identifier"],
"ruleInfo": {
"id": "6.11.1",
"severity": "error",
"category": "information",
"message": "The activity must have a planned start date or an actual start date.",
"link": {
"url": "https://iatistandard.org/en/guidance/standard-guidance/activity-dates-status/"
}
}
}
]
},
"range": {
"cases": [
{
"paths": ["capital-spend/@percentage"],
"min": 0.0,
"max": 100.0,
"ruleInfo": {
"id": "12.2.1",
"severity": "error",
"category": "financial",
"message": "The percentage value must be between 0.0 and 100.0 (inclusive).",
"link": {
"path": "activity-standard/iati-activities/iati-activity/capital-spend/"
}
}
}
]
}
}
}
Here we have a context: /iati-activities/iati-activity
, with a two named rules atleast_one and range which is applied in a number of cases - here just one each, with a single path each.
The ruleInfo
object includes metadata about the rule which is used in the Validator API.
The link
object can contain 2 possible keys which represent the Guidance Links for the rule:
url
is a full URL to the guidancepath
is the path to be added to the end of the reference documentation url for the version of standard. (e.g.https://iatistandard.org/en/iati-standard/{version}/{path}
)