From a5b7210b8a91c747f16259af3bbb2d07cea7c8e6 Mon Sep 17 00:00:00 2001 From: Rob Redpath Date: Wed, 28 Feb 2024 09:40:14 +0000 Subject: [PATCH] Update text in standard ruleset page for clarity --- .gitignore | 4 +++- en/rulesets/standard-ruleset.rst | 29 +++++++++++++++++++---------- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/.gitignore b/.gitignore index 852d8ced..5bacaac5 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,6 @@ en/_build .DS_Store fr/_build **/__pycache__ -.pytest_cache \ No newline at end of file +.pytest_cache +.vscode +.devcontainer diff --git a/en/rulesets/standard-ruleset.rst b/en/rulesets/standard-ruleset.rst index adef5a20..b88d5f8a 100644 --- a/en/rulesets/standard-ruleset.rst +++ b/en/rulesets/standard-ruleset.rst @@ -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 `_. 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 `_. +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 `_ 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 `_. + +Any errors, omissions or bugs should be reported via `GitHub `_ or to `IATI Support `_ 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 `_ as part of our `Single Source of Truth `_ 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 `_ as part of our `Single Source of Truth `_ 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. +