Standard Severity Levels with Schematron @role

Posted on December 21, 2018 by Rick Jelliffe

Each assert or report element (and, in fact, rules, patterns, etc) can have a role attribute. The intention of this attribute is to allow the assertion etc to be categorized, and the prime categorization we might use is severity.

So rather than validation being just either too-simple binary YES/NO, or the  unfocussed and large raw SVRL reports  (“un fluit diarrhea of gold” as Dali said of his ideas in his mad Spanfranglish), @role lets us categorize and filter results, such as into warnings, and so on.

Of course, most IDEs are based on this.  XML never caught up, because of the unpromising nature of grammars in this regard.

So here is a list of severity levels that I think Schematron tools and schemas might consider supporting. It is drawn from various IDEs and the Language Server Protocol.  I have added the equivalent LSP severity levels, and potential ISB severity levels.

  • @role="FATAL"  – something so bad that processing or validation should or did stop.
    • LSP Error
    • ISQB S1 CRITICAL
  • @role="ERROR"  – something  wrong has occurred but processing may continue
    • LSP Error
    • ISQB S2 MAJOR
  • @role="WARN"  – something wrong has happened, but it does not necessarily require action
    • LSP Warning
    • ISQB S3 MINOR
  • @role="CAUTION"  – It may not be wrong, but care is required. Or a system might be expected to process the document in a special way because of this.
    • LSP Information
    • ISQB S4 TRIVIAL
  • @role="INFO"  – some information is being reported
    • LSP Information
  • @role="HINT"  – some hint is being given to the user
    • LSP Hint
  • @role="TRACE"  – some information on execution is being reported.
    • LSP Information
  • @role="DEBUG"  – some information that is not intended for exposure in production.
    • LSP Hint

These severities also represent an order in which SVRL items might be presented to the user, if useful.

Typical use might be
<assert test="title" @role="ERROR">The title is required</assert>

Other examples are

  • <rule context="/"><assert test="/thing/@sku" @role="FATAL">It should be impossible that a thing has no sku</assert>
  • <rule context="something" @role="TRACE"> so that the svrl:fired-rules that match that rule are labelled in the SVRL, to verify that the rule is indeed matching
  • <rule context="/"><assert test="/thing/@version < 2" @role="CAUTION">Documents of older versions require extra validation.  Validate in phase "OLD"</assert>

Note that if you just want to put in a link to documentation, you don’t need to use  @role="INFO", you can use @see.

And if you just want to set, from a single assertion, some information that is global to the document, use @flag . For example, sch:assert/@flag="REJECT"might indicate that an pattern has failed in a way that makes all the SVRL assertions unreliable or distracting.  Or <sch:rule context="/households/person"><sch:report @test="ext:on-santas-naughty-list(name)" @role="CAUTION" @flag="AT_LEAST_ONE_NAUGHTY_PERSON">...might be used to flag that in this XML document there was found at least one person in this household who is on Santa’s Naughty List.