Skip to content

Vocabulary Mappings

FCC does not try to own every ontology. Instead, it ships mappings from external vocabularies into its own persona, action, and workflow concepts. This chapter describes the mapping primitive, the 20 packaged YAML files, and the procedure for adding a new mapping bundle.

The VocabularyMapping primitive

Every mapping is an instance of the frozen dataclass at src/fcc/objectmodel/mapping.py:

@dataclass(frozen=True)
class VocabularyMapping:
    source_id: str
    source_name: str
    source_vocabulary: str
    target_id: str
    target_name: str
    target_vocabulary: str
    similarity_score: float       # 0.0 – 1.0
    mapping_rank: int = 0         # rank among top-k
    requires_review: bool         # auto-True if score < 0.75
    created_at: datetime

The auto-computed requires_review flag is the quality gate. Any mapping with similarity below 0.75 is flagged for human review before it enters a production run.

The MappingStore protocol (same file) defines the collection contract — add, get_by_source, get_by_target, all, count.

The 20 packaged YAML files

FCC v1.3.x ships 20 vocabulary-mapping YAML files under src/fcc/data/objectmodel/. The full set is reproduced in the table below. The Entries column reports the number of - source_id: blocks in each file; totals are tracked in federation_benchmark.yaml and the total across all ecosystem projects sits at 95 packaged entries at the time of writing, with room to grow as sister projects publish more.

Ecosystem File Namespace Status
AOME aome_vocabulary_mappings.yaml aome Seeded
Athenium athenium_vocabulary_mappings.yaml athenium Seeded (v1.2.1)
Caelum caelum_vocabulary_mappings.yaml caelum Scaffold
Columba columba_vocabulary_mappings.yaml columba Scaffold
Constellation constel_vocabulary_mappings.yaml constel Seeded
Crater crater_vocabulary_mappings.yaml crater Scaffold
Crucible crucible_vocabulary_mappings.yaml crucible Seeded
CTO cto_vocabulary_mappings.yaml cto Seeded
Distiller distiller_vocabulary_mappings.yaml distiller Seeded
Libra libra_vocabulary_mappings.yaml libra Scaffold
Mnemosyne mnemosyne_vocabulary_mappings.yaml mnemosyne Seeded (v1.2.1)
Norma norma_vocabulary_mappings.yaml norma Scaffold
Ophiuchus ophiuchus_vocabulary_mappings.yaml ophiuchus Scaffold
PAOM paom_vocabulary_mappings.yaml paom Seeded
Pyxis pyxis_vocabulary_mappings.yaml pyxis Scaffold
Scutum scutum_vocabulary_mappings.yaml scutum Scaffold
Sentinel sentinel_vocabulary_mappings.yaml sentinel Seeded
Serpens serpens_vocabulary_mappings.yaml serpens Scaffold
Sky-Parlour skyparlour_vocabulary_mappings.yaml skyparlour Seeded
Vela vela_vocabulary_mappings.yaml vela Scaffold

"Scaffold" entries exist in the registry to reserve the namespace; the mappings themselves will be authored as each sister project publishes its first canonical schema in the v1.4.0 ecosystem pivot.

File format

Each file follows the same skeleton:

# <Vocabulary> vocabulary mapped to FCC concepts
# Source: <upstream source file or spec>
version: "1.0.0"
namespace: <ns>
description: >-
  <one-paragraph description>
mappings:
  - source_id: PAOM-ARCH-ANALYST
    source_name: Analyst
    source_vocabulary: paom
    target_id: RC
    target_name: Research Crafter
    target_vocabulary: fcc
    similarity_score: 0.88
    mapping_rank: 1

The loader at src/fcc/objectmodel/vocabulary_loader.py validates the schema, constructs VocabularyMapping instances, and registers them with the global MappingStore.

Mapping quality tiers

Mappings are implicitly tiered by similarity score:

Score range Tier Treatment
0.95 – 1.00 Exact Automatic use in production
0.75 – 0.94 Confident Automatic use, flagged in dashboard
0.50 – 0.74 Review required requires_review=True, human gate
0.00 – 0.49 Candidate only Excluded from federation resolution

The ConfidentMatchFilter in src/fcc/federation/resolver.py enforces the 0.75 cut during entity resolution. Review-tier mappings surface in the fcc dashboard vocabulary view.

Mapping workflow

The diagram below shows the round-trip for adding a new mapping bundle, from source inventory through human review to production use.

flowchart LR
    SRC[Source vocabulary<br/>e.g. FIBO, FHIR] --> INV[Inventory<br/>entities + attributes]
    INV --> DRAFT[Draft YAML<br/>src/fcc/data/objectmodel/]
    DRAFT --> VAL[fcc validate --vocab]
    VAL -->|errors| DRAFT
    VAL -->|ok| REV[Review tier 0.50-0.74]
    REV -->|approved| PROD[Production use]
    REV -->|rejected| REWORK[Rework mapping]
    REWORK --> DRAFT

Authoring checklist for a new bundle

Use this checklist when adding a new vocabulary bundle.

  • Source vocabulary has a stable identifier scheme
  • Each entity has an anchor in FCC (persona, action, workflow, or category)
  • Similarity scores are defensible — cite the method (manual, cosine, LLM)
  • Review-tier entries have a notes: field explaining the uncertainty
  • Namespace is registered in namespace_registry.yaml
  • File is added to the MkDocs sitemap if externally documented
  • fcc objectmodel assess --namespace <ns> produces a stage you expect

Ecosystem project co-evolution

FCC's mapping philosophy is that sister projects co-evolve with FCC through the VocabularyProviderPlugin pattern (v1.2.1+), not through runtime imports. Your plugin lives in your project's plugins/ directory and loads your vocabulary at FCC startup via the plugin system.

The 12 vocabulary provider plugins shipped in v1.2.1 — Athenium, Mnemosyne, etc. — are the reference implementations. Each one loads its own YAML, registers with the global MappingStore, and becomes queryable through UnifiedFacade.resolve().

See docs/developer/plugin-development.md for the full plugin authoring path.

See also