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 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
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:
[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:
invalid/dataset-350-no-agenttype.yamlleaves out the creator'sagentType, so it doesn't say whether the creator is a person or an organization.invalid/dataset-350-curie-type.jsonldwrites its@typeas the CURIE (abbreviated IRI)schema:Dataset, instead of the full IRIhttps://schema.org/Dataset. It's a JSON-LD file, so check it against the whole schema.
Rules the example has to satisfy¶
- The dataset needs
id,nameanddescription. Every subject term needsidandinDefinedTermSet. Every creator, publisher and funder needsidandagentType, and every place needsid. - A subject term's
idmust 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, includinghttporhttps. Write full IRIs: CURIEs such asDOID:3292are rejected. agentTypeis written as a CURIE:schema:Organizationorschema:Person.- Fields the model doesn't define are rejected. The JSON-LD keys
@contextand@typeare accepted. Each@typemust be the full IRI of its class.