Codifying "recommendations" and "warnings"

In the HSDS 2.1 upgrade workgroup I’ve seen and heard comments along the lines of “we should recommend this in the standard” or “the validator should warn if this is the case”.

The schema language that we use to ship HSDS, JSON Table Schema, doesn’t have a concept of a “recommendation” or a “warning”: things either fit the model, or they don’t.

Obviously, if we write custom validators, then we can do whatever we want - but that impacts on standardisation, and is potentially a nasty surprise if the text of the standard and the code of the validator get out of sync. The further out from the “core” / the closer to a particular context a particular piece of code is, the less this matters, in my view: the OR-UK validator accompanies a UK-specific profile and custom logic there is no bother, but if we want it to be useful across contexts, then we need to be able to understand the rules that are built into it, and potentially adapt them for our own contexts.

Documentation may well be enough: we already mark which pages are normative (i.e. are the rules) and which are non-normative (i.e. which are guidance). We’re looking at going further, and making sections normative or non-normative.

If we want to codify these things, though, then we need a technical answer. The way that we introduced the idea of a “deprecated” field into OCDS was by patching JSON Schema’s metaschema to introduce it, and validators (such the official OCDS validator) can parse that information to warn about deprecation.

That might be far too much effort, and documentation might be enough for now, but we should be mindful of this as we decide what to do about this.

As I suggested in another thread, we may go some way to avoid the need for “warnings” rather than errors in generic validators by keeping the core HSDS standard quite flexible and expecting stricter rules (like specific enumerations) to come in application profiles.

A deprecated field could be flagged as such in its text description and just not included in any current/new application profile.