Writing validation rules

Registration Authority validation rules can only be written and assigned by Registration Authority Managers and Registrars, or Registry Administrators.

Registry-wide validation rules can only be written and assigned by Registry Administrators.

Validation rules are written as YAML configuration files, and represent a single or series of checks against any metadata item that fits their criteria. A validation ruleset refers to a collection of validation rules.

Validation rule structure

The two mandatory elements of a validation rule are its status and its checks. Validation rules may also include an object, which specifies the metadata item type the rule will be applied to, but this element is non-mandatory.

Below is an example of a validation rule that includes all three of these elements:

- status: Standard
  object: DataElement
  checks:
    - validator: RegexValidator
      name: "Starts with a capital letter"
      severity: warning
      field: name
      regex: "[A-Z].+"

How to write a validation rule's status

A validation rule's status defines which metadata items the rule will apply to by looking for matching endorsement statuses in those items.

If a rule's status is set to 'Standard', for example, it will only run its checks against metadata items endorsed as 'Standard' by the relevant Registration Authority, or by any Registration Authority if the validation rule is registry-wide.

Valid statuses include:

• any: The validation rule will apply to all endorsed metadata items

• Not Progressed

• Incomplete

• Candidate

• Recorded

• Qualified

• Standard

• Preferred Standard

• Superseded

• Retired.

How to write a validation rule's checks

A validation rule's checks represent the specific attributes that the rule checks for in any metadata items it applies to.

Note: Because a check exists inside a rule, it must be appropriately indented.

Checks have their own structure, and must include a validator and a severity. Checks may also include a name, but this element is non-mandatory. These elements are defined below:

Validators

Currently available validators include:

• RegexValidators

• RelationValidators

• UniqueValuesValidators

• StatusValidators

RegexValidators

A RegexValidator checks the formatting of text fields via a specified 'regular expression' ('regex'). RegexValidators look for specific information inside metadata item fields, and require two additional elements be added to a validation rule to run:

• field: The name of the metadata item field being checked (in accordance to the registry API or GraphQL)

• regex: The rule that the chosen field is checked against. As a regex can include special characters, it's recommended to enclose it in quotation marks

  • Helpful regexes include:

    • Character regexes:

      • .: Any single character

      • [A-Z]: Any single uppercase letter

      • [a-z]: any single lowercase letter

      • [A-Za-z]: Any uppercase or lowercase letter

      • [0-9]: Any single digit

      • [0-9A-Za-z]: Any number, uppercase or lowercase letter.

    • Repetition regexes:

      • ?: Match 0 or 1 of the previous token. E.g. [A-Z]? will match "" (any empty string) or any single uppercase character

      • *: Match 0 or more of the previous token. E.g. [A-Z]* will match any number of uppercase characters

      • +: Match 1 or more of the previous token. E.g. [A-Z]+ will match a string with at least one uppercase character.

    • Positioning regexes:

      • ^: Match at the start of the line. E.g. ^A will only match if a string starts with a capital A

      • $: Match at the end of the line. E.g. Z$ will only match if a string ends with a capital Z.

Examples of rules containing RegexValidators include:

• Testing that a standard data element concept:

  • Starts with a capital letter

  • Includes a colon between the object class and property in its name.

- status: Standard
  object: DataElement
  checks:
    - validator: RegexValidator
      name: "Starts with a capital letter"
      severity: warning
      field: name
      regex: "[A-Z].+"

Note: The regex '.+' specifies any character ( . ), repeated any number of times ( + ).

• Testing that a standard data element has a definition of at least 100 characters

- status: Standard
  object: DataElement
  checks:
    - validator: RegexValidator
      name: Definition must be longer than 100 characters
      severity: warning
      field: name
      regex: ".{100,}"

RelationValidators

A RelationValidator checks whether specified metadata is attached to an item. RelationValidators require an additional element be added to a validation rule to run:

• field: The name of the metadata item field being checked (in accordance to the registry API or GraphQL). This must be a field that contains relation to another metadata item.

An example of a rule containing a RelationValidator can be found below:

• Testing that a data element has an associated value domain.

- status: Recorded
  object: DataElement
  checks:   
    - validator: RelationValidator
      severity: error
      field: valueDomain
      name: Value Domain should be linked to Data Element

UniqueValuesValidators

A UniqueValuesValidator checks whether value domains have unique values. Aristotle does not restrict the values used for codes in value domains; UniqueValuesValidators can be used to accommodate by checking that value domains have codes that are all unique.

An example of a rule containing a UniqueValuesValidator can be found below:

• Testing whether a value domain contains unique values.

- status: Recorded
  object: ValueDomain
  checks:   
    - validator: UniqueValuesValidator
      severity: error
      field: valueDomain
      name: Value Domain must have unique values

Note: This validator tests all permissible and supplementary values.

StatusValidators

A StatusValidator checks the status lifecycle of a metadata item. This can be used to confirm whether an item that has been endorsed as a certain status has met any business-required prerequisite statuses before this was done. StatusValidators require an additional element be added to a validation rule to run:

• status: A list of statuses that an item must have been endorsed as at least one of immediately prior to it being endorsed as its current status.

An example of a rule containing a StatusValidator can be found below:

• Testing that all metadata items have been endorsed as either 'recorded' or 'candidate' before 'standard'.

- status: Standard
  checks:   
    - validator: StatusValidator
      name: Candidate or Recorded -> Standard
      description: Metadata should progress along the lifecycle correctly
      severity: warning
      status:
        - Candidate
        - Recorded

Example ruleset

Below is a small collection of valid validation rules for your reference or use:

- status: any
  object: Indicator
  checks:
    - validator: RegexValidator
      name: "Name starts with Proportion of"
      severity: error
      field: name
      regex: "^Proportion of.*"
    - validator: RegexValidator
      name: "Name starts with Proportion of"
      severity: error
      field: name
      regex: "^Number of.*"
    - validator: RegexValidator
      name: "Rationale must not be empty"
      severity: error
      field: rationale
      regex: "^.(?:.|\\s)+$"
    - validator: RegexValidator
      name: "Computation description must not be empty"
      severity: error
      field: computation_description
      regex: "^.(?:.|\\s)+$"
    - validator: RegexValidator
      name: "Computation must not be empty"
      severity: error
      field: computation
      regex: "^.(?:.|\\s)+$"
    - validator: RegexValidator
      name: "Origin must not be empty"
      severity: error
      field: origin
      regex: "^.(?:.|\\s)+$"

- status: any
  object: DataElementConcept
  checks:
    - validator: RegexValidator
      name: "Name pattern must include a colon separator"
      severity: error
      field: name
      regex: ".+: .+"
    - validator: RelationValidator
      severity: error
      field: objectClass
      name: "Object Class linked to Data Element Concept"
    - validator: RelationValidator
      severity: error
      field: property
      name: "Property linked to Data Element Concept"

- status: any
  object: DataElement
  checks:
    - validator: RegexValidator
      name: "Name pattern must include a colon separator"
      severity: error
      field: name
      regex: ".+: .+"
    - validator: RegexValidator
      name: "Name pattern must include a comma"
      severity: error
      field: name
      regex: ".+, .+"
    - validator: RelationValidator
      severity: error
      field: valueDomain
      name: "Value Domain linked to Data Element"
    - validator: RelationValidator
      severity: error
      field: dataElementConcept
      name: "Data Element Concept linked to Data Element"