Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update text in standard ruleset page for clarity #775

Open
wants to merge 1 commit into
base: version-2.03
Choose a base branch
from
Open

Update text in standard ruleset page for clarity #775

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,6 @@ en/_build
.DS_Store
fr/_build
**/__pycache__
.pytest_cache
.pytest_cache
.vscode
.devcontainer
29 changes: 19 additions & 10 deletions en/rulesets/standard-ruleset.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,38 @@
################
Standard Ruleset
################
The Standard Ruleset is a collection of rules that cover most of the requirements of the IATI Standard and that a computer could, in principle, test. Typically, these are rules about the data that cannot be enforced by the IATI schema alone. It covers for example, the ordering of dates, percentages adding to 100, checks on the format of an iati-identifier and others.

We have created a generic framework that allows us to express many of these rules in a way that machines can understand and humans can interpret by reading a simple error message.
The Standard Ruleset is a collection of rules that complement the `IATI XML Schemas <https://github.com/IATI/IATI-Schemas>`_. Between them, they assess most of the requirements of the IATI Standard. The Standard Ruleset provides rules about the data that cannot be enforced by schema. For example, they include the ordering of dates, percentages adding to 100, and checks on the format of an iati-identifier.

The IATI Validator V2 uses these rules to programmatically validate IATI files. The code used to interpret these rules and validate an IATI file are part of the validator GitHub repository `IATI/js-validator-api <https://github.com/IATI/js-validator-api>`_.
Some aspects of the IATI Standard cannot be assessed automatically, such as "Is a title meaningful?". These rules are outside of the scope of the IATI XML Schemas and the Standard Rulesets, and should be assessed manually as part of publication.

There are some things given in definitions of elements that really only a human can interpret, such as "Is a title meaningful?". The Standard Ruleset does not even try to deal with cases such as this.
The `IATI Validator <http://validator.iatistandard.org>`_ uses these rules to programmatically validate IATI files. The code used to interpret these rules and validate an IATI file are part of the validator GitHub repository `IATI/js-validator-api <https://github.com/IATI/js-validator-api>`_.

Any errors, omissions or bugs should be reported via `GitHub <https://github.com/IATI/IATI-Rulesets/issues>`_ or to `IATI Support <https://iatistandard.org/en/contact/>`_


Using the Standard Ruleset
***************************
The current Standard Ruleset is a collection of rules that can be used to test the data in a single ``iati-activity`` or ``iati-organisation`` record.
The Standard Ruleset is a collection of rules that can be used to test the data in a single ``iati-activity`` or ``iati-organisation`` .

IATI data is often found as large files containing collections of (for example) activities, so to test a file of IATI data against the Standard Ruleset means running the tests on each ``iati-activity`` or ``iati-organisation`` in that file.

Every ``iati-activity`` or ``iati-organisation`` has the option to use different elements of the IATI Standard, and to also repeat certain elements, so in defining a Standard Ruleset it is necessary to include rules that may or may not need to apply for each individual ``iati-activity`` or ``iati-organisation`` .

IATI data is often found as large files containing collections of (for example) activities, so to test a file of IATI data against the Standard Ruleset means running the tests on each ``iati-activity`` or ``iati-organisation`` record in that file.
If we take a ``transaction`` from an ``iati-activity`` as an example, we can see that this element does not have to be reported. However, it may also be reported many times. There are rules in the Standard Ruleset to check that some of the data reported in transactions makes sense, so these tests could either be run many times, or not at all on a single ``iati-activity`` .

Every ``iati-activity`` or ``iati-organisation`` record has the option to use different elements of the IATI Standard, and to also repeat certain elements, so in defining a Standard Ruleset it is necessary to include rules that may or may not need to apply for each individual ``iati-activity`` or ``iati-organisation`` record.
Hence, the number of tests undertaken on an ``iati-activity`` or ``iati-organisation`` can vary according to the content.

If we take a ``transaction`` from an ``iati-activity`` record as an example, we can see that this element does not have to be reported. However, it may also be reported many times. There are rules in the Standard Ruleset to check that some of the data reported in transactions makes sense, so these tests could either be run many times, or not at all on a single ``iati-activity`` record.
Relationship to the IATI Standard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hence, the minimum and maximum number of tests undertaken on an ``iati-activity`` or ``iati-organisation`` can fluctuate according to the content.
Where the standard says that something MUST be the case, these are defined in the Standard Ruleset as rules, which will produce an Error if the condition is not met.

Where the standard says that something SHOULD be the case, these are defined in the Standard Ruleset as guidance, which will produce a Warning if the condition is not met.


Full list of IATI Rules
^^^^^^^^^^^^^^^^^^^^^^^

The full list of IATI rules are defined in a `JSON file <https://github.com/IATI/IATI-Rulesets/blob/version-2.03/rulesets/standard.json>`_ as part of our `Single Source of Truth <https://iatistandard.org/en/guidance/developer/ssot/>`_ that can be consumed programmatically. The list below has been generated from that source. You can see the error/warning message in plain English and also an id link that would direct you to the source JSON. You will see in the JSON file there that there is a severity reference. All MUST statements are defined as errors (rules) and all SHOULD statement are defined as warnings (recommended guidance).
The full list of IATI rules are defined in a `JSON file <https://github.com/IATI/IATI-Rulesets/blob/version-2.03/rulesets/standard.json>`_ as part of our `Single Source of Truth <https://iatistandard.org/en/guidance/developer/ssot/>`_ that can be consumed programmatically. The list below has been generated from that source. You can see the error/warning message in plain English and also an id link that would direct you to the source JSON. You will see in the JSON file there that there is a severity reference.

Loading