IATI Ruleset Spec¶

An IATI Ruleset is a JSON document. The structure is described below.

A JSON schema is availible 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 below CASE_DICT is a dictionary where the contents depend on RULE_NAME CASE_DICT_ARRAY is an array of case dictionaries. The contents of each dictionary depend on the RULE_NAME

The possible keys in a case dictionary are:

condition: An xpath string. If this evaluates to True, the rule will be ignored.
eval: 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.
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 followed.
all: A string containing the condition that must be met for all elements if one is not met.
foreach: An array of xpath strings. Containing a set of xpaths to be evaluated under a different rule.
do: An array of rules. To evaluate with foreach.
subs: An array of xpath strings. These are to be evaluated with the rules in do.

Rule Names¶

Rule names are listed in bold

Keys: The keys for each rule are then listed.

Followed by a brief description of the rule’s function.

no_more_than_one

Keys: condition, paths

There must be no more than one element described by the given paths.

atleast_one

Keys: condition, paths

There must be at least one element described by the given paths.

only_one_of

Keys: excluded, paths

If there’s a match of the elements in excluded, there must not be any matches in paths, if there are no matches in excluded, there must be exactly one element from paths.

one_or_all

Keys: one, all

one must exist otherwise all other attributes or elements must exist.

dependent

Keys: condition, paths

If one of the provided paths exists, they must all exist.

sum

Keys: condition, paths, sum

The numerical sum of the values of elements matched by paths must match the value for the sum key

date_order

Keys: condition, less, more

The date matched by less must not be after the date matched by more. If either of these dates is not found, the rule is ignored.

date_now

Keys: date

The date must not be after the current date.

time_limit

Keys: start, end

The difference between the start date and the end date must not be greater than a year.

between_dates

Keys: date, start, end

The date must be between the start and end dates.

regex_matches

Keys: condition, paths, regex

The provided regex must match the text of all elements matched by paths

regex_no_matches

Keys: condition, paths, regex

The provided regex must match the text of none of the elements matched by paths

startswith

Keys: condition, paths, start

The text of each element matched by paths must start with the text of the element matched by start

unique

Keys: condition, paths

The text of each of the elements described by paths must be unique

if_then

Keys: condition, cases, if, then

If the condition evaluated in if is true, then then must resolve to true as well

loop

Keys: foreach, do, cases, subs

All elements in foreach are evaluated under the rules inside do

strict_sum

Keys: paths, sum

The decimal sum of the values of elements matched by paths must match the value for the sum key