Best practice for properties with external controlled vocabularies

[mnizol]

What is the best practice for properties that should be constrained based upon an external controlled vocabulary? For example, suppose we are defining a JSON Schema for a healthcare encounter and wish to constrain a procedureCode field to use terms from LOINC (http://loinc.org). For small controlled vocabularies, enum is the obvious choice. But enum seems inadequate when (a) the list of values is very large and/or (b) the list of values is controlled by another organization.

I can think of a few alternatives to enum for this use case, but I'm curious if the community has identified best practice in this area:

1. Define the property as a string with format uri and a pattern set to match the controlled vocabulary's URL. Example JSON Schema snippet:
   {"procedureCode": { "type": "string", "format" : "uri", "pattern": "https:\/\/loinc.org"}
   Example instance:
   {"procedureCode": "https://loinc.org/80726-3/"}
   This has the nice property that terms are self-describing; however, validating that a term is actually valid for the given controlled vocabulary would require a custom validator.

2. Create a custom format in which the format's value is the URL of the controlled vocabulary. Example JSON Schema snippet:
   {"procedureCode": { "type": "string", "format": "https://loinc.org"}
   Example instance:
   {"procedureCode": "80726-3"}
   This is attractive in that because we use the standard format attribute to capture the URL of the controlled vocabulary, we can use standard mechanisms to extend the validator's format checker (e.g., via a custom decorator in the Python jsonschema library).

3. Introduce a non-standard attribute in the JSON Schema to capture the URL of the controlled vocabulary. Example JSON Schema snippet:
   {"procedureCode":{"type": "string", "controlled-vocabulary": "https://loinc.org"}
   Example instance:
   {"procedureCode": "80726-3"}
   This approach makes the intent very clear at the cost of using a non-standard attribute that isn't supported by validator implementations.

Do any of the above options seem reasonable? Is there an alternative approach that the community considers to be best practice in this area?

[karenetheridge]

{ "type": "string", "format": "https://loinc.org"}

This isn't valid in JSON Schema. Are you proposing that it be valid? What is on the other end of that URI?

There is already wording in the specification about extra vocabularies, and a few implementations already support vocabulary extensions: https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.1

[mnizol]

Thank you @karenetheridge. I think the term "vocabulary" might be overloaded here. My interpretation of section 8.1 is that that provides a mechanism for extending JSON Schema's meta-schema. My question is regarding best practice for specifying a constraint on a string property that restricts that string to a large set of allowed values. In my question above, I used the term "controlled vocabulary" for such a constraint. JSON Schema includes the enum keyword, which is useful when the set of allowed values is relatively small. But there are scenarios in which the set of allowed values is very, very large (e.g., all procedure codes maintained by LOINC, or all drug codes maintained by WHO, or all names maintained by VIAF). An enum is impractical for such scenarios, both because of the size of the allowed set and because the allowed set is maintained by another organization. Is there a best practice for this scenario?

[karenetheridge]

I think your choices are pretty much:

• download the list of possible values and transform that data into a schema that holds the values in an enum,
• create a new vocabulary keyword that does exactly what you want.

[Relequestual]

The "best practice" solution is to define your own vocabulary with a new keyword which does what you want.

The problem with this approach is you might struggle to find tooling which supports "vocabularies" right now.

Your considerations are, how is the schema going to be used?

Is it going to be used by only you internally and no one else? Or is it going to be shared externally.

If it's going to be shared externally, you should consider defining your own vocabulary. Previously similar work has been done to point to an ontology as a controlled vocabulary using a custom keyword.

Adding custom keywords without defining a vocabulary is possible, but then you have interoperability issues if someon using the schema doesn't get the memo about the addtional keyword. (Unknown keywords in JSON Schema are ignored, and so the validation using that keyword simply wouldn't happen.)

You should also consider the fact that you might be adding non-determanistic validation results.
Does the controlled vocabulary have a version attached? Is the controlled vocabulary downloaded at runtime / once every day / one time for each version? It depends on how important it is that data is always valid according to the schema, and the source and structure of the data.

[cmungall]

Hi @mnizol and @Relequestual, very interesting discussion!

A variant of 1 is to make complete ontology term objects part of the schema. Some semi-standard datamodels here include FHIR codeableconcepts:

• http://www.hl7.org/implement/standards/fhir/datatypes.html#codeableconcept

The Human Cell Atlas developed their own extension to JSON-Schema and built validators that use the EBI Ontology Lookup Service. See for example:

https://github.com/HumanCellAtlas/metadata-schema/blob/master/json_schema/module/ontology/cell_cycle_ontology.json

This schema is used for properties whose values must be terms from CCO or GO

they use an "ontology" object to represent an ontology term:

"ontology": {
            "description": "An ontology term identifier in the form prefix:accession.",
            "type": "string",
            "graph_restriction":  {
                "ontologies" : ["obo:hcao", "obo:go"],
                "classes": ["GO:0007049", "GO:0022403"],
                "relations": ["rdfs:subClassOf"],
                "direct": false,
                "include_self": false
            },
            "user_friendly": "Cell cycle ontology ID",
            "example": "GO:0051321; GO:0000080"
        },

You can see the "graph_restriction" (not part of json-schema of course) that describes dynamically the set of allowed terms. This kind of pattern is sometimes known as an "intensional value set".

The adaptive immune receptor repertoire (AIRR) standard has a not dissimilar pattern for intensional value sets

Their schema is Open-API using the x-airr extension but the same patterns could be applied to json-schema

https://github.com/airr-community/airr-standards/blob/master/specs/airr-schema-openapi3.yaml

This is an example from AIRR where the value of the species property must come from the "gnathostome" branch OBO ontology rendering of NCBITaxon (this seems like an obscure root node but it's to do with conservation of key parts of the vertebrate immune system):

species:
            $ref: '#/Ontology'
            nullable: false
            description: Binomial designation of subject's species
            title: Organism
            example:
                id: NCBITAXON:9606
                label: Homo sapiens
            x-airr:
                miairr: essential
                adc-query-support: true
                set: 1
                subset: subject
                name: Organism
                format: ontology
                ontology:
                    draft: false
                    top_node:
                        id: NCBITAXON:7776
                        label: Gnathostomata

And in @Relequestual's own GA4GH schema:

https://github.com/ga4gh-discovery/ga4gh-case-discovery/blob/00eb25f5ff963e4494cb5538ee811a39c78cb6b5/json_schema/schemas_source/components/record/phenotype.yaml#L17-L24

There is a pattern to ensure the CURIE matches but no checks on branches

This is similar to the concept of "intensional value sets" that are found in clinical informatics (see for example the VSAC server: https://vsac.nlm.nih.gov/)

and are formally encoded using FHIR: https://build.fhir.org/valueset.html#int-ext

UPDATE (2022-08-12)

I posted about this particular problem here https://douroucouli.wordpress.com/2022/07/15/using-ontologies-within-data-models-and-standards/, including a solution for LinkML, that can be compiled to JSON-Schema

UPDATE (2022-09-16)

There was some previous work done on extending JSON Schema to support ontologies at the biohackathon, notes here

[Relequestual]

I remember seeing an ajv extension which would handle the EBI OLS calls, but I can't find that anymore.
Good to hear from you again @cmungall - I do quite miss doing GA4GH work sometimes!
I hope to have a case study with HCA soon... soon-ish. It's in progress!

[GabenGar]

Can't a enum be replaced with oneOf statement and thus allow the choice between arbitrary but annotated items?