MIDAS Catalog JSON-LD Metadata Architecture

Executive Summary

FAIR Compliance Notes

Under the current F-UJI profile, a representative Dataset record earns 25 of 26 points. The unmet metrics do not reflect deficient metadata practices:

Resource Type Architecture

The MIDAS Catalog metadata system supports 10 primary resource types, each with specialized Schema.org mappings optimized for their specific use case:

Metadata Standards Integration

Core Standards (All Resources)

• Schema.org – Primary vocabulary for web discoverability
• Dublin Core Terms (DCTERMS) – Academic metadata interoperability
• DCAT – Data catalog vocabulary for dataset portals
• PROV-O – Provenance tracking for data lineage
• PAV – Authoring and versioning metadata

Domain-Specific Standards

• Bioschemas Dataset Profile – Life sciences data extension
• MIDAS Metadata Vocabulary – Custom epidemiology terms
• OBO Ontologies – Disease, pathogen, and host classification
• GeoNames – Geographic location standardization
• LRMI (Learning Resource Metadata Initiative) — Educational metadata for learning resources. Namespace prefix: lrmi → https://purl.org/dcx/lrmi-terms/

Health & Medical Standards (Conditional)

• HL7 FHIR – Healthcare interoperability (health-related data)
• SNOMED CT – Clinical terminology (health records)
• LOINC – Laboratory observations (clinical data)

Additional Standards

• DataCite – Research data citation
• ORCID – Researcher identification

JSON-LD Architecture Components

JSON-LD Access Points

The JSON-LD metadata for each MIDAS Catalog record is available through multiple mechanisms:

The same records are also published in a second, LinkML form, with its own per-record and whole-catalog files. See LinkML for MIDAS Catalog.

Record Identifiers

Each catalog record is identified by a persistent identifier — a w3id PURL of the form https://w3id.org/midas-catalog/{id} — which serves as the record's @id and dcterms:identifier and resolves to its landing page at https://catalog.midasnetwork.us/collection/{id}. This is a persistent-identifier scheme; no DOIs are minted — the persistent identifier is the w3id PURL itself.

Context Flattening & Vocabulary Namespaces

All @context definitions are consolidated at the root level, removing nested contexts for cleaner JSON-LD structure and improved parser compatibility.

{
  "@context": {
    "@vocab": "https://schema.org/",
    "dcterms": "http://purl.org/dc/terms/",
    "dcat": "http://www.w3.org/ns/dcat#",
    "prov": "http://www.w3.org/ns/prov#",
    "pav": "http://purl.org/pav/",
    "geonames": "https://www.geonames.org/ontology#",
    "lrmi": "https://purl.org/dcx/lrmi-terms/",
    ...
  }
}

Consumer Documentation

The architecture embeds human-readable property documentation directly in the @context:

{
  "@context": {
    "about": {
      "@id": "https://schema.org/about",
      "@comment": "Subject matter of the content. Contains DefinedTerm objects (topics, biological scales, types)."
    }
  }
}

Dublin Core & DCAT Equivalences

Dublin Core and DCAT equivalences are carried by dedicated camelCase keys that the @context resolves to their canonical IRIs, so FAIR assessment tools see the equivalent Dublin Core / DCAT terms without any colon-prefixed keys appearing in the record body. IRI-valued equivalences are @id-coerced:

{
  "dcSubject": ["http://purl.obolibrary.org/obo/MONDO_0005108"],
  "dctSpatial": ["https://sws.geonames.org/6252001/"]
}

JSON Schema Validation

Each JSON-LD record includes a self-reference to its defining JSON Schema, enabling consumers to programmatically validate records they harvest or process.

Schema Self-Reference

Every JSON-LD record references the schema in two ways:

1. conformsTo declaration — The schema appears as a dcterms:Standard entry in the conformsTo array alongside the other metadata standards:

{
  "conformsTo": [
    {
      "@type": "http://purl.org/dc/terms/Standard",
      "@id": "https://catalog.midasnetwork.us/schema/midas-catalog-jsonld.schema.json",
      "name": "MIDAS Catalog JSON-LD Schema",
      "description": "JSON Schema (Draft 2020-12) defining the structure of MIDAS Catalog JSON-LD metadata records",
      "url": "https://catalog.midasnetwork.us/schema/midas-catalog-jsonld.schema.json",
      "standardType": "metadata schema",
      "standardVersion": "1.0.1",
      "subjectAreas": ["epidemiology", "metadata", "data validation"]
    }
  ]
}

The standardVersion field tracks the output-shape version, so a consumer can detect shape changes directly from the record itself.

2. @context reference — A describedby entry in the context points directly to the schema URL, providing a lightweight discovery mechanism:

{
  "@context": {
    "describedby": "https://catalog.midasnetwork.us/schema/midas-catalog-jsonld.schema.json"
  }
}

JSON-LD Output Schema

The MIDAS Catalog publishes a JSON Schema that defines and validates the structure of all published JSON-LD metadata records. It is written in version 2020-12 of the JSON Schema standard. The schema is programmatically generated from the Java class hierarchy that produces the JSON-LD, ensuring it always stays in sync with the actual output.

Published at: https://catalog.midasnetwork.us/schema/midas-catalog-jsonld.schema.json

Schema Structure

The schema uses $defs to define reusable component types that mirror the Java class hierarchy:

The root schema uses anyOf to discriminate between 10 resource types based on their @type value. Each resource type definition uses allOf to compose the shared CreativeWorkProperties with type-specific extensions.

Using the Schema

Any developer can fetch the schema and validate JSON-LD records in their language of choice:

1. Fetch the schema from https://catalog.midasnetwork.us/schema/midas-catalog-jsonld.schema.json
2. Fetch individual records from https://catalog.midasnetwork.us/jsonld/{id}.jsonld or the bulk file from https://catalog.midasnetwork.us/jsonld/catalog.jsonld
3. Validate each record against the schema with a JSON Schema library that supports version 2020-12 (see Validation Tools below; libraries exist for Python, R, JavaScript, Java and most other languages)

Validation Tools

• Online: json-schema.hyperjump.io (recommended — supports Draft 2020-12 and handles @ and : characters in property names)
• Python: jsonschema
• R: jsonvalidate
• JavaScript: Ajv
• Java: networknt/json-schema-validator (v1.0.87 for Java 8)

FAIR Principles Compliance

Overall Score: 96.2% (25/26 points)

These figures are the F-UJI measurement of a representative Dataset record (record 350) against the live catalog (catalog.midasnetwork.us).

The MIDAS Catalog achieves strong FAIR compliance while acknowledging current limitations in community metadata standardization. Scores vary by resource type and, within a type, by dimension.

Findable (100%)

• F1: Every record carries a persistent w3id PURL identifier — @id and dcterms:identifier resolve to https://w3id.org/midas-catalog/{id}, a recognized persistent-identifier scheme served through the w3id.org redirect system
• F2: Rich metadata in machine-readable Schema.org/JSON-LD
• F3: Identifiers embedded in metadata — @id and dcterms:identifier carry the w3id PURL, schema:identifier carries the bare native record code, and url carries the direct landing page (https://catalog.midasnetwork.us/collection/{id})
• F4: Indexed by Google Dataset Search, DataCite, FAIRsharing

Accessible (100%)

• A1: HTTPS access with content negotiation
• A1.1: Open protocol (HTTP/HTTPS)
• A1.2: No authentication required for metadata (HTML pages, static JSON-LD files, and sitemap are all publicly accessible)
• A2: Metadata persistence (landing pages maintained even if data moves)

Interoperable (100%)

• I1: Formal knowledge representation (Schema.org, DCTERMS, DCAT). Educational resources additionally use LRMI terms, extending Dublin Core for pedagogical metadata.
• I2: Controlled vocabularies (OBO, GeoNames, SNOMED CT)
• I3: Qualified references to other resources (hasPart, wasDerivedFrom)

Reusable (83.3%)

R1: Rich Metadata with Usage Information

• License clearly stated (schema:license, dcterms:license)
• Provenance tracked (PROV-O, PAV)
• Detailed attribution (creator, publisher, pavAuthoredBy)
• Usage rights documented (schema:usageInfo, dcterms:rights)

R1.3-02D-1: Data Format in Metadata

Why Landing Pages Over Direct Downloads

1. Link Persistence: Data providers frequently reorganize file structures. Landing pages remain stable; direct file URLs break. Our schema:url and dcat:landingPage provide reliable access.
2. Essential Context: Landing pages provide usage documentation, terms of service, citation requirements, related resources, and version information.
3. User Guidance: Multiple format options explained, data quality notes, processing recommendations, and support contact information.

Format Information Still Available

The underlying data formats ARE documented in machine-readable form:

{
  "distributions": [{
    "@type": ["https://schema.org/DataDownload", "dcat:Distribution"],
    "url": "https://landing-page-with-download-links",
    "encodingFormat": "text/csv",
    "mediaType": "https://www.iana.org/assignments/media-types/text/csv"
  }]
}

Provenance & Attribution Architecture

MIDAS implements comprehensive provenance tracking using complementary standards:

PROV-O (W3C Provenance Ontology)

{
  "wasGeneratedBy": {
    "@type": "prov:Activity",
    "prov:used": [/* source entities */],
    "prov:wasAssociatedWith": [/* creators */]
  },
  "wasDerivedFrom": {
    "@type": "prov:Entity",
    "prov:wasAttributedTo": {/* original authors */}
  }
}

PAV (Provenance, Authoring, Versioning)

{
  "pavCreatedBy": {/* system/organization */},
  "pavAuthoredBy": {/* intellectual author */},
  "pavDerivedFrom": "original-source-url",
  "pavCreatedOn": "2024-09-05",
  "pavLastUpdateOn": "2024-01-09"
}

Geographic & Temporal Coverage

GeoNames Integration

All geographic locations reference authoritative GeoNames entries. The Place node is the GeoNames entity: it is emitted under the places key (mapped to schema:spatialCoverage), dual-typed schema:Place + geonames:Feature, with its @id set to the GeoNames concept URI (https://sws.geonames.org/{id}/). The geonames: prefix remains the ontology namespace for the Feature type and the featureCode / featureClass terms.

{
  "places": [{
    "@type": ["https://schema.org/Place", "geonames:Feature"],
    "@id": "https://sws.geonames.org/6252001/",
    "dcIdentifier": "https://sws.geonames.org/6252001/",
    "identifier": "6252001",
    "name": "United States",
    "featureCode": "PCLI",
    "featureClass": "A"
  }]
}

Geographic Resolution Levels

Geographic resolution is one of several DB-backed controlled lists carried in the additionalProperty bag — a consumer-visible structure in which each entry is a schema:PropertyValue keyed by propertyID to its category IRI, with the term itself in valueReference. The same structure carries the other controlled lists (topic, digital object type, and so on).

{
  "@type": "https://schema.org/PropertyValue",
  "name": "Geographic Resolution",
  "propertyID": "http://w3id.org/midas-metadata/midas03",
  "value": "Country",
  "valueReference": {
    "@type": ["https://schema.org/DefinedTerm", "skos:Concept"],
    "@id": "http://rdfs.co/juso/Country",
    "name": "Country",
    "inDefinedTermSet": "http://w3id.org/midas-metadata/midas03"
  }
}

Temporal Coverage (ISO 8601)

{
  "temporalCoverage": "2021-12-31/2024-01-09",
  "dcTemporal": "2021-12-31/2024-01-09"
}

Format: start-date/end-date or start-date/... for ongoing data collection.

Controlled Vocabularies & Ontologies

Subject Classification Hierarchy

MIDAS metadata uses structured DefinedTerm objects from established ontologies:

{
  "about": [
    {
      "@type": ["https://schema.org/DefinedTerm", "skos:Concept"],
      "@id": "http://purl.obolibrary.org/obo/IDO_0000436",
      "name": "infectious disease",
      "displayName": "Infectious Disease",
      "description": "...",
      "inDefinedTermSet": "http://w3id.org/midas-metadata/midas2",
      "dcIdentifier": "http://purl.obolibrary.org/obo/IDO_0000436"
    }
  ],
  "keywords": [/* flat array of topic-name strings (for discovery) */]
}

The SKOS tie is expressed as a dual @type (schema:DefinedTerm + skos:Concept), not a sameAs. Each term carries inDefinedTermSet, the IRI of the controlled axis it belongs to — the key to reading the additionalProperty bag. All four controlled-vocabulary axes now carry inDefinedTermSet: topic (midas2), digital object type (midas10), geographic resolution (midas03), and biological scale (midas5). keywords is a separate flat array of topic-name strings re-added for discovery (e.g., Google Dataset Search), not a subset of the about objects.

Vocabulary Sources

Best Practices & Design Rationale

1. Multiple Vocabulary Mappings

Key properties are expressed under multiple vocabularies. Dublin Core / DCAT equivalences are emitted as dedicated camelCase mirror keys that the @context resolves to their canonical IRIs:

• subject → schema:about and dcterms:subject (mirror key dcSubject)
• spatialCoverage → schema:spatialCoverage and dcterms:spatial (mirror key dctSpatial)

Benefit: Maximizes compatibility with different harvesters and tools.

2. Embedded Documentation

The @context includes human-readable @comment fields explaining each property's purpose and usage.

Benefit: Self-documenting metadata that aids both humans and automated tools.

3. Graceful Degradation

If a harvester doesn't understand PROV-O or PAV, basic Schema.org properties (creator, publisher, datePublished) still provide essential information.

Benefit: Ensures baseline discoverability even with limited parser capabilities.

4. Extensibility

Custom MIDAS terms use additionalType to add domain-specific semantics without breaking Schema.org compliance.

Benefit: Serves epidemiology community needs while maintaining broad interoperability.

5. ConformsTo Declarations

Every resource explicitly declares which metadata standards it follows via dcterms:conformsTo, including a reference to the JSON Schema that validates its structure:

{
    "conformsTo": [
      {
        "@type": "http://purl.org/dc/terms/Standard",
        "name": "Schema.org",
        "standardType": "generic",
        "subjectAreas": ["sciences", "web"]
      },
      {
        "@type": "http://purl.org/dc/terms/Standard",
        "name": "Bioschemas Dataset Profile",
        "standardType": "metadata schema",
        "subjectAreas": ["bioinformatics", "life sciences"]
      },
      {
        "@type": "http://purl.org/dc/terms/Standard",
        "@id": "https://catalog.midasnetwork.us/schema/midas-catalog-jsonld.schema.json",
        "name": "MIDAS Catalog JSON-LD Schema",
        "description": "JSON Schema (Draft 2020-12) defining the structure of MIDAS Catalog JSON-LD metadata records",
        "url": "https://catalog.midasnetwork.us/schema/midas-catalog-jsonld.schema.json",
        "standardType": "metadata schema",
        "standardVersion": "1.0.1",
        "subjectAreas": ["epidemiology", "metadata", "data validation"]
      }
    ]
  }

Benefit: Transparent declaration of compliance for automated FAIR assessment. The schema reference enables consumers to programmatically discover and validate against the exact structure specification.

Integration Points

Google Dataset Search

MIDAS JSON-LD is optimized for Google's structured data requirements:

• Embedded in HTML <script type="application/ld+json">
• Static JSON-LD files at predictable URLs (/jsonld/{id}.jsonld); the sitemap.xml lists every record's landing page, where the same JSON-LD is embedded
• Bulk JSON-LD file at /jsonld/catalog.jsonld for full-catalog harvesting
• JSON Schema at /schema/midas-catalog-jsonld.schema.json for structure validation
• Includes all required properties (name, description, url)
• Uses recommended optional properties (temporalCoverage, spatialCoverage — emitted under the places key — and keywords)

DataCite Integration

Via dcterms:bibliographicCitation and DataCite schema in conformsTo:

{
  "bibliographicCitation": "CDC. 2022-2023 U.S. Map & Case Count. 2022. Available from: https://..."
}

FAIR Assessment Tools

References

MIDAS Schemas & Bulk Data

• JSON-LD Output Schema: https://w3id.org/midas-catalog/schema/midas-catalog-jsonld.schema.json
• Bulk JSON-LD (all records): https://catalog.midasnetwork.us/jsonld/catalog.jsonld
• LinkML form of the catalog: LinkML for MIDAS Catalog
• Sitemap: https://catalog.midasnetwork.us/sitemap.xml

Standards Documentation

• Schema.org: https://schema.org/
• Bioschemas Dataset: https://bioschemas.org/profiles/Dataset/
• Dublin Core: https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
• DCAT: https://www.w3.org/TR/vocab-dcat/
• PROV-O: https://www.w3.org/TR/prov-o/
• PAV: https://pav-ontology.github.io/pav/
• GeoNames: https://www.geonames.org/ontology/documentation.html
• LRMI: https://www.dublincore.org/specifications/lrmi/

FAIR Assessment

• F-UJI: https://f-uji.net/
• FAIR Principles: https://www.go-fair.org/fair-principles/
• RDA Metadata Standards: https://rdamsc.bath.ac.uk/

MIDAS Resources

• MIDAS Catalog: https://catalog.midasnetwork.us/
• MIDAS Metadata Vocabulary: https://w3id.org/midas-metadata/
• Example JSON-LD: https://catalog.midasnetwork.us/jsonld/350.jsonld
• JSON-LD Output Schema: https://w3id.org/midas-catalog/schema/midas-catalog-jsonld.schema.json
• Bulk JSON-LD: https://catalog.midasnetwork.us/jsonld/catalog.jsonld
• Sitemap: https://catalog.midasnetwork.us/sitemap.xml