Semantic Resource Card Proposal

[crakerb-ship-it]

My silicon friend and I chatted and reviewed a few existing resources to come up with the below. It is a combination of SKOS, DCAT-3, and ISO19135-1.

Some of the ISO19135-1 might be a little much depending on what governance model we go with and how much formality we want in the process but included to at least discuss. It is based on a 19135 derived check list we developed for managing semantic resources within AgGateway so I think includes a few tweaks on how we implemented 19135 for our purposes.

# --- SemanticResource card schema v0.2 ---
# Standards alignment:
#   DCAT-3      — catalog/access metadata
#   SKOS        — vocabulary/concept type
#   Dublin Core Terms (dcterms) — provenance
#   ISO 19135-1 — registration governance metadata
#   LinkML-compatible YAML

# ===========================================
# SECTION 1: IDENTITY
# ISO 19135 — itemIdentifier, unique, never reused
# ===========================================
id: <string>                    # required; unique slug or URI; never reused (ISO 19135 itemIdentifier)
name: <string>                  # required; human-readable name (dcterms:title)
description: <string>           # recommended (dcterms:description)

# ===========================================
# SECTION 2: RESOURCE CLASSIFICATION
# SKOS + DCAT
# ===========================================
resource_type: <string>         # required; what kind of artifact
  # controlled values:
  # ontology | codelist | thesaurus | classification_scheme |
  # data_model | subject_heading | linked_data_term | document | software

resource_format: <string>       # optional; how it is expressed
  # controlled values:
  # OWL | SKOS | RDF-Turtle | JSON | JSON-LD | PDF | HTML | R-package | other

# ===========================================
# SECTION 3: PROVENANCE
# dcterms:publisher, dcterms:spatial, dcterms:language
# ===========================================
institution: <string>           # required (dcterms:publisher)
region: <string>                # optional (dcterms:spatial — broad region)
country: <string>               # optional (dcterms:spatial — ISO 3166 code)
language: <string>              # optional; default "en" (dcterms:language)
license: <URI or string>        # recommended (dcterms:license)

# ===========================================
# SECTION 4: ACCESS
# DCAT-3 dcat:landingPage / dcat:accessURL
# ===========================================
url: <URI>                      # required; primary access point
alternate_urls:                 # optional; additional distributions (DCAT dcat:distribution)
  - url: <URI>
    format: <string>
    label: <string>

# ===========================================
# SECTION 5: REGISTRATION STATUS
# ISO 19135 — item status (usability signal to end users)
# Distinct from workflow state (see Section 6)
# ===========================================
status: <string>                # required
  # controlled values (ISO 19135):
  # valid | invalid | superseded | retired | candidate # Candidate I do not believe is in 19135 but we use to add to a registry and give a little time to make sure everything is correct. Kind of a "use at your own risk" flag providing an opportunity to fix things if something is wrong with a new entry without having to go through the whole submission/correction process. 

# ===========================================
# SECTION 6: REGISTRATION PROVENANCE
# ISO 19135 
# ===========================================
registration:
  date_accepted: <date>         # when item entered the register (ISO 19135)
  date_amended: <date>          # most recent clarification (ISO 19135)
  submitter: <string>           # person or org that proposed this entry (ISO 19135)
  submitting_org: <string>      # organization (ISO 19135 SubmittingOrganization)

# ===========================================
# SECTION 7: CHANGE HISTORY
# ISO 19135 req. 15–20 — predecessor/successor, modification record
# ===========================================
superseded_by: <id>             # if status=superseded; ISO 19135
replaces: <id>                  # dcterms:replaces / ISO 19135 predecessor
amendments:                     # ISO 19135 clarification log
  - date: <date>
    description: <string>       # justification of change (req. 17)

# ===========================================
# SECTION 8: RELATIONSHIPS
# SKOS semantic relations; dcterms:isPartOf
# ===========================================
part_of: <id>                   # for entries that are part of a larger resource
related: [<id>, ...]            # skos:related
broader_resource: <id>          # skos:broadMatch at resource level

# ===========================================
# SECTION 9: DOMAIN TAGGING
# dcat:keyword / skos:subject
# ===========================================
soil_topics: [<string>, ...]    # domain keywords; candidate for a controlled list

# ===========================================
# SECTION 10: EDITORIAL
# Internal use only; not for display
# ===========================================
notes: <string>                 # editorial notes
last_reviewed: <date>           # for curation tracking

[ktoddbrown]

Here is an alternative format that is proposed:

soil-ontology-informatics-cluster/soil_data_landscape/soil_data_cards/semantics_USGSThesaurus.md

Lines 1 to 40 in 1ef0d03

	---
	type: semantics
	title: USGS Thesaurus
	description: The USGS Thesaurus provides a controlled vocabulary of scientific concepts relevant to the mission and work of the USGS.
	resource: https://apps.usgs.gov/thesaurus/
	tags:
	- dictionary
	- hierarchy_of_terms
	- discovery
	---
	This is the recommended annotation language for archiving [[organization_USGS]] data products.
	# Summary
	(Purpose and content below is from the [main page](https://apps.usgs.gov/thesaurus/))
	> The USGS Thesaurus provides a controlled vocabulary of scientific concepts relevant to the mission and work of the USGS. This controlled vocabulary helps to categorize USGS information and allows people and computers to find collections of information resources that have common characteristics.
	>
	> The USGS Thesaurus is structured as a hierarchy of terms because relationships between concepts are represented. For example, _Sciences_ is broad and general concept. A more specific type of _Sciences_ is _Earth Sciences_. In the USGS Thesaurus, _Sciences_ is a broader or parent term to Earth Sciences. The USGS Thesaurus has the following top-level categories that are used to group scientific concepts.
	>
	> 1) Sciences: Major educational fields, fields of study, and professional groupings within USGS.
	> 2) Methods: Techniques, methods, procedures, or strategies for research, management, collection, or analysis of scientific information in USGS.
	> 3) Topics: Themes, subjects, and concerns for which USGS information resources are relevant.
	> 4) Product types: General representation of the information in a resource, such as a map or dataset.
	> 5) Time periods: Geologic time periods and seasons of the year.
	> 6) Institutional structures and activities: Activities, processes, and organizational concepts.
	>
	> The thesaurus is limited in depth and specificity of coverage. It does not attempt to replicate existing controlled vocabularies such as AGI's GeoRef. The intention is to provide sufficient contextual cues for the information seeker to determine the relevance of a resource for his or her concern, not to locate precisely the answer to a specific user question.
	# Format
	Below are the available formats as of 2026-06-22
	|File or package|Format|Size|Contents|
	|---|---|---|---|
	|[update-usgs-thesaurus.sql](https://apps.usgs.gov/thesaurus/download/update-usgs-thesaurus.sql)|SQL|417 kB|SQL code to update your copy of the USGS Thesaurus|
	|[thesauri.zip](https://apps.usgs.gov/thesaurus/download/thesauri.zip)|SQLite|8 MB|USGS Thesaurus and other public thesauri|
	|[USGSThesaurus.rdf](https://apps.usgs.gov/thesaurus/download/USGSThesaurus.rdf)|RDF-XML|963 kB|SKOS for USGS Thesaurus only (lacks Use-With terms)|
	|[CommonGeographicAreas.rdf](https://apps.usgs.gov/thesaurus/download/CommonGeographicAreas.rdf)|RDF-XML|73 MB|SKOS or Common Geographic Areas thesaurus|
	|[CMECS.rdf](https://apps.usgs.gov/thesaurus/download/CMECS.rdf)|RDF-XML|575 kB|SKOS for Coastal and Marine Ecological Classification System|
	|[MarinePlanningData.rdf](https://apps.usgs.gov/thesaurus/download/MarinePlanningData.rdf)|RDF-XML|99 kB|SKOS for Data Categories for Marine Planning|