Write a record in YAML¶
This page is a reference for a record's structure: its fields, and the rules its identifiers follow. For a step-by-step walkthrough, see the tutorial on LinkML for MIDAS Catalog.
The examples come from dataset-350.yaml, a complete, valid Dataset record. It is
written in YAML, a plain-text format for data:
# A minimal, valid MIDAS Catalog Dataset, modeled on catalog record 350
# (https://catalog.midasnetwork.us/collection/350).
#
# Check it with:
# linkml-validate -s midas-catalog.yaml -C Dataset dataset-350.yaml
id: https://w3id.org/midas-catalog/350
name: "2022-2023 U.S. Map & Case Count"
description: >-
The archived dataset (CSV) contains Mpox and Orthopoxvirus confirmed
cumulative case and death counts in each U.S. state and territory, including
cases of non-U.S. residents in the U.S from 2022-2023. The data are
downloadable and also visible on the website on a U.S. map and in a table.
creator:
- id: https://www.cdc.gov/
agentType: schema:Organization
name: Centers for Disease Control and Prevention of the United States
about:
- id: http://purl.obolibrary.org/obo/DOID_3292
name: mpox
inDefinedTermSet: http://w3id.org/midas-metadata/midas2
places:
- id: https://sws.geonames.org/6252001/
name: United States
Fields¶
A Dataset needs three fields. The others are optional. These are the ones most records use:
| Field | Required | What it holds |
|---|---|---|
id |
yes | A web address that identifies the dataset |
name |
yes | The dataset's title |
description |
yes | What the data is |
creator |
no | A list of the people and organizations who made the dataset |
publisher |
no | One organization that makes the dataset available |
about |
no | A list of subjects, each a term from a vocabulary |
places |
no | A list of places the dataset covers |
keywords |
no | A list of topic words, as plain text |
url |
no | The web address of a page about the dataset |
datePublished |
no | The date the dataset was published, written YYYY-MM-DD |
temporalCoverage |
no | The dates the data covers, written YYYY-MM-DD/YYYY-MM-DD, or YYYY-MM-DD/.. if the data is ongoing |
Each field name links to its page in the Model Reference. The
Dataset page lists
every field a dataset can have. A field the model doesn't define is rejected.
Identifiers¶
An identifier is an IRI: a web address used as a name for something. The checks compare identifiers
exactly, as text. So http and https count as different, even when both open the same page in a browser.
Write every identifier in full. A CURIE (abbreviated IRI) such as DOID:3292 is rejected.
The record. The dataset's id is any web address that identifies it, such as its DOI address
(https://doi.org/…) or its landing page. Catalog records use https://w3id.org/midas-catalog/ followed
by the record's number.
Creators and publishers. Each one needs an id: a web address that identifies it. For an
organization, use its website. For a person, use their ORCID address
(https://orcid.org/…).
Subjects. Each subject in about is a term from a vocabulary. Its id is the term's IRI. Its
inDefinedTermSet says what kind of subject it is, and that decides which vocabularies its id may come
from:
| Kind of subject | inDefinedTermSet |
The id must start with |
|---|---|---|
| Topic, such as a disease | http://w3id.org/midas-metadata/midas2 |
http://purl.obolibrary.org/obo/, http://w3id.org/midas-metadata/, http://edamontology.org/, http://www.ontodm.com/OntoDM-core/ or http://vocabs.lter-europe.net/EnvThes/ |
| Digital object type | http://w3id.org/midas-metadata/midas10 |
http://purl.obolibrary.org/obo/ or http://w3id.org/midas-metadata/ |
| Geographic resolution | http://w3id.org/midas-metadata/midas03 |
http://rdfs.co/juso/, https://www.wikidata.org/wiki/, http://www.geonames.org/ontology#, http://schema.org/, https://schema.org/ or http://w3id.org/midas-metadata/ |
| Biological scale | http://w3id.org/midas-metadata/midas5 |
http://w3id.org/midas-metadata/ |
http://purl.obolibrary.org/obo/ is the start of every OBO Foundry ontology's
IRIs, such as the Disease Ontology's. It uses http, not https.
Places. Each place's id is its GeoNames IRI, written
https://sws.geonames.org/{number}/, with https and the trailing slash.
agentType¶
Each creator and publisher needs an agentType. It says what kind of agent it is: schema:Organization
for an organization, or schema:Person for an individual. Write it exactly as shown. It's the one field written as a CURIE,
because it names a type rather than identifying a thing.
Finding identifiers¶
Finding a subject's identifier. Search the Disease Ontology for the
disease. Its page shows the term's full identifier, such as http://purl.obolibrary.org/obo/DOID_3292 for
mpox, with a Copy button. Use that full address, not the short form shown above it (DOID:3292).
Finding a place's identifier. Search GeoNames for the place. The number in
its page's address is its GeoNames number, such as 6252001 for the United States. Write it as
https://sws.geonames.org/6252001/, with the trailing slash.
Check it¶
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 install LinkML into a private Python environment (a virtual environment):
Check the record with LinkML's validator,
linkml-validate. -s gives it the model's YAML file,
and -C Dataset tells it to check the record as a Dataset:
To check your own record, save it as a .yaml file in the same folder. Then run the same command with your
file's name in place of dataset-350.yaml. Check a record shows what an
error looks like.