I’ve spent this afternoon down a rabbit-hole, but I think I’ve got my own thinking straight on this after a discussion with @davidraznick and a lot of time to think.
As I see it, HSDS describes how data about services (and related concepts, such as organisations and locations) can be structured. If structured in the way that HSDS describes, organisations can publish information about those services; this might be in bulk, or on a row-by-row basis via an API.
Sometimes, an organisation or community wants to describe something that HSDS doesn’t provide the language for; this could be an entirely new concept, or additional information about an existing concept.
In other cases, an organisation or community finds that, in order to be useful, fields that are optional in HSDS are essential for them, or that fields need to use a specific format in order to be useful. For example, OR-UK makes the optional phones.contact_id field mandatory, and we’ve discussed in workgroup meetings how it would be helpful to add constraints around which taxonomies are used.
These are the kinds of changes to the standard that are often described as “extensions” and “profiles”. However, these terms are used inconsistently, which doesn’t help our conversations.
Right now, there are a limited number of these sets of changes: there’s OR-UK, and our recent work on FHIR interoperability. We’ve discussed potential for some more - such as a more ambitious baseline quality standard, a profile for 211s, and something for AIRS users.
Each of these has particular characteristics that mean that it differs from the others, but we can look for groupings that help us to reason about them and work out how to support them.
One thing that I think is true of all of these cases is that they all add additional constraints. Some - but not all - also introduce new fields or objects.
In other standards, the term “extension” is usually used to describe the addition of fields: in FHIR for example, “Every element in a resource can have extension child elements to represent additional information”. OCDS extensions are - in the main - similar; they add new functionality to OCDS without taking anything away. Extensions are often modular and composable: someone can take one or more extensions, combine them and build on them to create a new extension, and put that into use.
What constitutes a “profile” is more ambiguous; in FHIR a profile is “A set of constraints on a resource”, whereas OCDS profiles can be far-reaching, including extensions, new constraints, and additional documentation.
Other terms in this space include “application profile” and “Implementation Guides”, which also bring together the concepts described above.
I think that we need a definition for HSDS that helps us make sure that we’re all talking about the same thing.
I think that there are three components to this:
- New objects, concepts and fields
- New constraints - such as required fields, data formats or allowable taxonomy values
- Guidance and documentation: help and advice tailored to specific audiences, which might speak specifically to the new additions or constraints, or might be addressing common issues among the target audience with HSDS implementation in general.
I don’t think that we need to separate these out, in the way that other standards do. The kinds of uses that we’re talking about don’t build on each other in the way that other standards’ extensions do, even if they might be applicable at the same time. And, we’re talking about less than 10 such artefacts in the foreseeable future, rather than dozens from the off.
So, here’s my proposal:
First, we define a “profile” as being a set of one or more of:
- New objects, concepts and fields
- New constraints
- New guidance and documentation relating to the additions above
- New or altered guidance and documentation relating to HSDS implementation
…with five rules:
- Nothing a profile does can stop data being valid HSDS against the base schema
- Wherever possible, existing HSDS fields and objects must be used
- Wherever possible, existing HSDS patterns should be followed - or new patterns should be discussed with the community before adoption
- Profiles must be clear about how they are governed: either through the Open Referral governance process, or by the community that uses it
- Profiles must make it clear how they differ from base HSDS
Second, we define some more terms:
To “extend” the standard is to add new objects, concepts and fields to it.
To “constrain” the standard is to add new rules to it.
To use a profile “descriptively” is to use it to describe the properties of the data.
To use a profile “prescriptively” is to constrain “valid” data in a particular context to only data which uses a particular profile
Third, we agree to reserve the term “extension” for future use: we may want to build the kind of modular system that we see elsewhere, and it would be helpful not to already have used the word.
Finally, we build some tech to support all of this:
- Space across the docs site for profiles to draw attention to the relevance of the documentation for the profile
- Space within the docs site to document the profiles completely
- A way to compare the schema for a profile with the base schema and to visualise the results
- A pattern for extensions to follow, so that it’s easy to see examples and understand what each extension is doing.
Technologically speaking, we’re already a lot of the way there. HSDS 3.0 is encoded as a directory of JSON files, one per object. Profiles can be created as a new directory, containing the files of any objects that have been changed. We can add in folders for changes to taxonomies and codelists, and incorporate any reconciliation necessary into the build process.
Documentation changes can either be handled manually, or we can look at building a standardised way for profiles to inject content across the docs site; that’s quite straightforward. We’ll encourage developers to document their work through a comment mechanism, as well.
My apologies for a 1000-word update to a 6-month-old forum post! But, I think this is important for us to work out. I’d appreciate any reactions, responses or reckons - if we need to discuss this on a future call then of course I’m very happy to, but also it might be that I’m just saying what you all already think, in which case, thank you for indulging me.