Controlled Vocabulary Governance Workflow

Use this workflow when you need to add, revise, or align controlled terms used in salmon datasets, salmon data package metadata, and SPSR uploads.

Note

This workflow is for term governance.

If you are preparing a dataset package and uploading to SPSR, use Salmon data package + SPSR intake path.

Canonical source and namespace

Step 1 — Identify candidate terms from real data

For each candidate term, capture:

  • proposed label
  • plain-language definition
  • where it appears (column name, code list, method field)
  • expected usage context (FSAR, SPSR wizard, reporting)
  • source/provenance reference (document, method spec, report)

Step 2 — Check existing ontology and vocabularies first

Before proposing anything new:

  1. Search WIDOCO for exact or close matches.
  2. Check existing concept schemes and synonyms.
  3. Decide whether your candidate is:
    • existing term (reuse as-is)
    • synonym/label variant (add lexical support)
    • genuinely new concept (new term needed)

Step 3 — Choose the right modeling type

  • Use OWL classes/properties for domain entities and logical relations.
  • Use SKOS concepts for controlled code lists and enumerations.
  • Do not model the same concept as both OWL class and SKOS concept unless there is an explicit architecture decision.

Step 4 — Prepare a term request package

Minimum required fields:

  • preferred label
  • definition (IAO:0000115 for OWL or skos:definition for SKOS)
  • provenance (IAO:0000119 and/or dcterms:source when available)
  • owner/theme/module
  • example usage
  • requested placement (parent class, scheme membership, broader term)

Step 5 — Review and decision

Apply a light governance check:

  • no duplicate meaning
  • definition is testable and non-circular
  • naming is consistent
  • aligns with competency questions and downstream workflows
  • impact on salmon data package and SPSR workflows is documented

Step 6 — Implement and publish

After approval:

  1. Add/update ontology term(s).
  2. Regenerate ontology docs and release artifacts.
  3. Update DSU docs if contributor guidance changed.
  4. Update downstream mappings/templates as needed.

Step 7 — Sync downstream systems (including SPSR)

When term changes affect intake:

  • update salmon data package templates (column_dictionary.csv, codes.csv examples)
  • update SPSR upload guidance and controlled-value references
  • run one end-to-end test through SPSR wizard with the updated term usage

Useful SPSR references:

Quick checklist