Skip to content

Check a record

This page checks the example record in two ways. First, LinkML's own validator, linkml-validate, checks it as a Dataset. Then check-jsonschema checks it against the model's published JSON Schema. A JSON Schema describes which fields a record may have and what each field may hold. For a step-by-step version, see the tutorial on LinkML for MIDAS Catalog.

The MIDAS Catalog publishes its records as JSON-LD, which is JSON for linked data. A JSON-LD record adds two keys to the plain data. @context links each field name to its definition on the web. @type says what kind of thing the record is, and can say the same for each object inside it. Both point to things by IRI: a web address used as an identifier, such as https://schema.org/Dataset. The JSON Schema checks a record either way, as plain data (.yaml or .json) or as JSON-LD (.jsonld), exactly as written.

Set up

You need Python 3.11 or newer (https://www.python.org/downloads/).

Download the example files as the Examples page shows, and run these commands in that folder. They create a private Python environment (a virtual environment) and install the tools into it:

python3 -m venv venv
source venv/bin/activate
pip install linkml==1.11.1 check-jsonschema rfc3986-validator

linkml==1.11.1 is the LinkML version that generates the published files. It includes linkml-validate. rfc3986-validator lets check-jsonschema check the fields that must hold a URI (a web address). Without it, check-jsonschema skips that check. A creator url such as not-a-web-address then passes.

Check it as a Dataset

linkml-validate reads the model's YAML file, midas-catalog.yaml, which you downloaded with the example files. -s gives it that file. -C Dataset tells it to check the record as a Dataset. Without -C, it stops with the error Multiple potential target classes found, because the model has more than one type of record. linkml-validate reads YAML and JSON files alike:

linkml-validate -s midas-catalog.yaml -C Dataset dataset-350.yaml dataset-350.json
No issues found

linkml-validate can't check the JSON-LD file. Check it against the whole schema instead, as the next section shows.

Check it against the whole schema

check-jsonschema checks a record against the published JSON Schema. The schema covers every record type, and a JSON Schema validator checks against the whole schema. So this check confirms that the record is a valid catalog record, but not which type it is. It rejects anything that isn't a valid record of some type, even {"nonsense": 1}. It reads all three files, including the JSON-LD one, exactly as written:

check-jsonschema --schemafile https://w3id.org/midas-catalog/linkml/schema.json dataset-350.yaml dataset-350.json dataset-350.jsonld
ok -- validation done

What an error looks like

In invalid/dataset-350-bad-subject.yaml, the subject is the Disease Ontology's term for mpox, but its IRI starts with https instead of http:

about:
  - id: https://purl.obolibrary.org/obo/DOID_3292
    name: mpox
    inDefinedTermSet: http://w3id.org/midas-metadata/midas2

Check it with linkml-validate:

linkml-validate -s midas-catalog.yaml -C Dataset invalid/dataset-350-bad-subject.yaml
[ERROR] [invalid/dataset-350-bad-subject.yaml/0] 'https://purl.obolibrary.org/obo/DOID_3292' does not match '^(http://purl\\.obolibrary\\.org/obo/|http://w3id\\.org/midas-metadata/|http://edamontology\\.org/|http://www\\.ontodm\\.com/OntoDM-core/|http://vocabs\\.lter-europe\\.net/EnvThes/).+$' in /about/0/id

The message gives the value that was rejected, and the pattern it must match. At the end, /about/0/id names the field: the id of the first subject in about. The pattern lists how the field's IRIs may start. The Disease Ontology's terms start with http://purl.obolibrary.org/obo/, with http. The pattern compares text, so the https version doesn't match. To fix the record, change https back to http.

The other two invalid files are rejected too:

Rules the example has to satisfy

  • The dataset needs id, name and description. Every subject term needs id and inDefinedTermSet. Every creator, publisher and funder needs id and agentType, and every place needs id.
  • A subject term's id must start with one of the namespaces its field accepts. A namespace is the start that all IRIs from one vocabulary share. Namespaces are matched exactly, including http or https. Write full IRIs: CURIEs such as DOID:3292 are rejected.
  • agentType is written as a CURIE: schema:Organization or schema:Person.
  • Fields the model doesn't define are rejected. The JSON-LD keys @context and @type are accepted. Each @type must be the full IRI of its class.