Skip to content

FCC Ontology Integration

Adapting an external standard ontology into FCC is the most common knowledge-engineering task. This guide walks through the end-to-end pattern using the 10 constellation projects as worked examples, each anchoring a specific external ontology:

Constellation Vertical External Ontology Reference
Ophiuchus Healthcare FHIR R5 + SNOMED CT HL7 FHIR
Serpens Healthcare research FHIR R5 + HL7 CDA HL7
Libra Legal LKIF + LegalRuleML OASIS
Crater Insurance ACORD + ISO 12812 ACORD
Scutum Government NIEM + DCAT-US GSA / DOJ
Norma Energy CIM (IEC 61970 / 61968) IEC
Pyxis Finance FIBO + ISO 20022 EDM Council / ISO
Vela Retail GS1 + schema.org GS1 / W3C
Columba Transport CityGML + DATEX II OGC / EU
Caelum Climate / Earth ENVO + DCAT-US + OGC OBO / GSA

Each pattern below is reusable across constellations and downstream verticals.

The Integration Pipeline

flowchart LR
    A[External<br/>ontology] --> B[Study<br/>source]
    B --> C[Identify<br/>FCC targets]
    C --> D[Author<br/>mapping YAML]
    D --> E[Author<br/>plugin shim]
    E --> F[Validate]
    F --> G[Federate]
    G --> H[Ground<br/>RAG]

    classDef step fill:#e3f2fd,stroke:#0d47a1;
    class A,B,C,D,E,F,G,H step;

Step 1 — Study the Source Ontology

Every serious integration starts with a literature review:

  • Read the specification document (FHIR, FIBO, etc.)
  • Identify the core concepts (typically 50-150 for a vertical)
  • Identify the relationships (is-a, part-of, regulated-by, etc.)
  • Identify the licence and attribution requirements
  • Identify the versioning convention

Budget 3-5 days for a mid-sized ontology. An ontology you know well may take only a day; one new to you may take two weeks.

Step 2 — Identify FCC Targets

Not every external concept maps into FCC. The target concepts are those that:

  • Appear in a persona's R.I.S.C.E.A.R. spec (e.g. Patient for a healthcare persona)
  • Are part of a workflow deliverable (e.g. ClaimForm for Crater)
  • Ground a RAG grounding vocabulary (e.g. any Person type)
  • Participate in the knowledge graph (e.g. nodes in the compliance evidence graph)

A good rule of thumb: if a concept does not touch an FCC persona, workflow, or knowledge-graph node, it probably does not belong in the vocabulary mapping. Keep the mapping focused.

Step 3 — Author the Mapping YAML

Author src/fcc/data/objectmodel/<yourproject>_vocabulary_mappings.yaml. The schema is in Vocabulary Provider Pattern. Full working example from the Pyxis project (anchoring FIBO):

vocabulary:
  name: pyxis
  version: 1.0.0
  namespace: https://constellation.fcc/pyxis/ontology#
  source: "FIBO Production 2024 Q4 + ISO 20022 Message Catalogue"
  license: CC-BY-4.0
  authority_tier: 2

concepts:
  - id: pyxis:Customer
    label: Customer
    definition: "A party who has a financial relationship with the institution."
    synonyms: [Client, AccountHolder]
    external_ids:
      fibo: "fibo-fnd-pty-rl:Customer"
      iso20022: "Party39Choice"
    broader: pyxis:Party
    examples:
      - "An individual with a checking account"
      - "A corporate treasury desk"

  - id: pyxis:Account
    label: Account
    definition: "A record of financial obligations between parties."
    external_ids:
      fibo: "fibo-fbc-fi-fi:FinancialInstrument"
      iso20022: "CashAccount40"
    broader: pyxis:FinancialInstrument

  - id: pyxis:Transaction
    label: Transaction
    definition: "A transfer of value between parties."
    external_ids:
      fibo: "fibo-fbc-pas-fpas:Transaction"
      iso20022: "pacs.008.001.10"
    narrower: [pyxis:Payment, pyxis:Trade]

Step 4 — Author the Plugin Shim

See Vocabulary Provider Pattern for the full template. The plugin's only job is to load the YAML at activation time and expose the list of mappings.

Step 5 — Validate

fcc audit vocabulary --strict --provider pyxis
fcc audit federation  --strict --namespace pyxis

Fix findings before proceeding. Common early findings:

  • Missing external_ids for concepts that clearly have equivalents in other standards
  • Orphan broader / narrower links (concept referenced but not defined)
  • Licence field not using an SPDX identifier
  • Namespace IRI not reachable (HEAD fails)

Step 6 — Federate

Once validation passes, register the namespace in federation_config.yaml (or let the plugin entry-point auto-register it). Run:

fcc federation peer-check --namespace pyxis

This walks your external_ids and confirms at least one peer namespace has a matching concept. Complete isolation is allowed but not useful — it means the RAG pipeline cannot cross-reference.

Step 7 — Ground the RAG Pipeline

The RAG pipeline at src/fcc/rag/ accepts an optional grounding vocabulary. When provided, retrieved chunks are filtered for relevance to concepts in the vocabulary and re-ranked for concept density. See RAG Pipeline Guide.

Adaptation Patterns by Ontology

FHIR (Ophiuchus, Serpens)

FHIR ships JSON Schema and StructureDefinitions. The adaptation pattern:

  1. Pick the resource types you need (Patient, Observation, Condition, etc.)
  2. Flatten StructureDefinition to a concept list
  3. Preserve the http://hl7.org/fhir/... IRI as external_ids.fhir
  4. Keep cardinality hints in the examples field (FCC does not model cardinality directly)

Ophiuchus ships ~120 FHIR-aligned concepts.

FIBO (Pyxis)

FIBO is RDF-native, which makes it easy. The adaptation pattern:

  1. Use rdflib to load the FIBO module you need
  2. Emit one concept per owl:Class
  3. Preserve the FIBO IRI as external_ids.fibo
  4. Translate rdfs:subClassOf into broader

Pyxis ships ~80 FIBO-aligned concepts.

ACORD (Crater)

ACORD XML schemas are verbose. The adaptation pattern:

  1. Focus on the AL3 / XML Life/P&C schemas your deployment touches
  2. Emit one concept per top-level XML type
  3. Capture XPath snippets in examples for implementers
  4. Preserve the ACORD version in the source field

Crater ships ~60 ACORD-aligned concepts.

NIEM (Scutum)

NIEM is federal-U.S. oriented. The adaptation pattern:

  1. Identify the NIEM release (currently 5.x)
  2. Pick the core + domain namespaces you need (Core + hs / j / etc.)
  3. Preserve structures:id as external_ids.niem_id
  4. Bridge to DCAT-US for dataset-level metadata

Scutum ships ~70 NIEM-aligned concepts.

CIM (Norma)

CIM is power-utility-oriented. The adaptation pattern:

  1. Choose the CIM profile your deployment implements (IEC 61970 for transmission, 61968 for distribution)
  2. Emit one concept per top-level UML class
  3. Preserve the CIM URI as external_ids.cim
  4. Handle the enumeration-heavy style with care — enumerations become their own concepts

Norma ships ~55 CIM-aligned concepts.

DCAT-US (Caelum, Scutum)

DCAT-US is dataset-metadata oriented. The adaptation pattern:

  1. Map Dataset, Distribution, DataService as top-level concepts
  2. Preserve dcat: IRIs as external_ids.dcat
  3. Bridge to ISO 19115 metadata for geospatial
  4. Use the ordinary FCC Contact and Organization concepts for responsibility statements

Licensing Considerations

External ontologies have licences. Most are permissive for reuse (CC-BY, MIT, Apache), but some require attribution or forbid derivation:

Ontology Licence Restriction
FHIR HL7 open Attribution required
FIBO CC-BY 4.0 Attribution required
SNOMED CT Affiliate licence Country-specific terms
ACORD Member licence Membership required
NIEM Public domain (U.S. Govt) None
CIM Restricted / member IEC membership may be required
DCAT-US Public domain (U.S. Govt) None
ENVO CC-0 None

Record the licence in the YAML vocabulary.license field and in the evidence graph. For restricted ontologies, ship only the concept IDs — do not copy definitions verbatim.

Versioning Across Ontology Upgrades

When the upstream ontology publishes a new release:

  1. Pin the old version's file as <project>_vocabulary_mappings_v<N>.yaml
  2. Author the new mapping as the primary file
  3. Bump vocabulary.version (major if concept IDs changed, minor otherwise)
  4. File an ADR (OPEN-SCI-008) describing the migration
  5. Update the ChangeTracker entry
  6. Re-run the federation benchmark

Keep the old file in the tree for at least one minor release cycle so downstream consumers can migrate on their schedule.