Skip to content

FCC Namespace Registration

Cross-project federation in FCC is built on namespaces. Each project — whether a constellation vertical (Ophiuchus, Libra, Pyxis) or a downstream consumer (PAOM, AOME, CONSTEL) — registers a namespace with the federation registry. Concepts within a namespace are addressed using the namespace:concept_id convention, and cross-namespace relationships are resolved by the EntityResolver.

This guide explains how the registry works, how to register a new namespace, and what conformance the registry enforces.

The reference code:

  • src/fcc/federation/namespace.py — NamespaceRegistry
  • src/fcc/federation/resolver.py — EntityResolver
  • src/fcc/federation/registry.py — FederationRegistry
  • src/fcc/federation/tracker.py — ChangeTracker
  • src/fcc/data/objectmodel/federation_config.yaml — authoritative namespace list

The 19-Project Vendored Inventory

FCC ships with 19 namespaces pre-registered. Snapshot (as of v1.3.9):

Namespace Project Role
fcc FCC core Canonical framework
paom PAOM Consumer
aome AOME Consumer
constel CONSTEL Constellation orchestration
crucible Crucible Ecosystem authority
cto CTO Object-model bridge
distiller Distiller Reference project
sentinel Sentinel Governance tooling
skyparlour SkyParlour Visualization
athenium Athenium Financial vocab
mnemosyne Mnemosyne Memory vocab
ophiuchus Ophiuchus Healthcare vertical
serpens Serpens Healthcare research
libra Libra Legal vertical
crater Crater Insurance vertical
scutum Scutum Government vertical
norma Norma Energy vertical
pyxis Pyxis Finance vertical
vela Vela Retail vertical

Two additional placeholders (columba, caelum) are reserved for transport and climate and will move to registered status in a later minor release.

Open src/fcc/data/objectmodel/federation_config.yaml to see the authoritative current list.

Why Namespaces Matter

A namespace does three things:

  1. Disambiguates. fcc:Customer and pyxis:Customer can have different definitions without conflict.
  2. Routes queries. When the EntityResolver sees pyxis:Customer, it knows which vocabulary provider to query.
  3. Tracks provenance. Every concept's lineage is identifiable by namespace + ID + version.

Federation without namespaces collapses into terminological chaos; this is a lesson every mature ontology stack has learned.

The NamespaceRegistry

from fcc.federation.namespace import NamespaceRegistry

registry = NamespaceRegistry.from_package_data()

# Enumerate known namespaces
for ns in registry.all():
    print(f"{ns.prefix:12s} {ns.iri:50s} owner={ns.owner}")

# Resolve a concept reference
concept = registry.resolve("pyxis:Customer")
print(concept.definition)

# List peers
peers = registry.peers_of("fcc")

The registry is immutable at runtime: namespaces are registered at package import time and locked thereafter. Dynamic registration is only permitted through the plugin entry-point mechanism.

Registering a New Namespace

There are three ways to register a namespace, from easiest to hardest:

fcc scaffold-vertical-project \
    --codename yourcodename \
    --vertical retail \
    --ontology-anchor "GS1 + schema.org"

The scaffold command (added in v1.3.0) generates:

  • Project skeleton with CTO/CONSTEL patterns
  • Namespace entry in federation_config.yaml
  • Empty vocabulary mapping YAML
  • Plugin shim boilerplate
  • Test harness

This is the supported path for new verticals joining the constellation.

Path B — VocabularyProviderPlugin Entry Point

For downstream consumers already shipping a Python package, register via pyproject.toml entry points (see Vocabulary Provider Pattern). The plugin's provider_name() determines the namespace prefix.

Path C — Manual Edit (Core Framework Only)

For FCC-core canonical additions, edit src/fcc/data/objectmodel/federation_config.yaml directly. This path is restricted to FCC maintainers.

The Namespace Descriptor

Every registered namespace carries the following metadata in federation_config.yaml:

namespaces:
  - prefix: pyxis
    iri: https://constellation.fcc/pyxis/ontology#
    owner: INFORMATION COLLECTIVE, LLC / Pyxis project
    purpose: "Financial vertical vocabulary anchoring to FIBO and ISO 20022"
    authority_tier: 2
    license: CC-BY-4.0
    version: 1.0.0
    contact: "pyxis@example.org"
    homepage: "https://github.com/rollingthunderfourtytwo-afk/pyxis"
    status: active

All fields are required. Missing fields trigger a QG-FED-NS-001 audit finding.

Authority Tiers

Tier Examples Precedence
1 fcc Highest — always wins conflicts
2 Constellation verticals (ophiuchus, libra, pyxis, …) Wins against tier 3
3 Consumers (paom, aome, constel, cto) Wins against tier 4
4 Ad-hoc plugins Lowest

If two namespaces assert conflicting information about the same external concept, the higher-tier namespace wins by default and the conflict is logged as a finding. See Vocabulary Provider Pattern.

Cross-Namespace Concept Resolution

The EntityResolver walks three kinds of relationships to resolve cross-namespace references:

  1. Direct external_id match — both concepts share an external ID (e.g. both map to fibo:Party)
  2. Declared same_as — a concept explicitly states equivalence to a peer
  3. Declared broader_than / narrower_than — hierarchy traversal
from fcc.federation.resolver import EntityResolver

resolver = EntityResolver.from_package_data()

# Find the FCC-canonical equivalent of pyxis:Customer
equivalents = resolver.equivalents("pyxis:Customer")
for eq in equivalents:
    print(f"{eq.concept_id:30s} via {eq.via}")

Resolution is transitive and cycle-safe; the resolver terminates when no new equivalents appear.

The ChangeTracker

Every vocabulary or namespace change is recorded by the ChangeTracker. This is essential for audit trails and for re-running historical queries.

from fcc.federation.tracker import ChangeTracker

tracker = ChangeTracker.from_package_data()

# What changed in pyxis between v0.9 and v1.0?
diff = tracker.diff("pyxis", "0.9.0", "1.0.0")
for change in diff.changes:
    print(f"{change.kind:12s} {change.concept_id}: {change.detail}")

ChangeTracker outputs feed into the compliance evidence graph and the namespace-registration audit section of fcc audit.

Registration Conformance Tests

Before your namespace is accepted into the registry, it must pass:

fcc audit federation --strict --namespace mynamespace

The audit checks:

  • Namespace descriptor is complete (QG-FED-NS-001)
  • IRI resolves to a document (HEAD request; QG-FED-NS-002)
  • Authority tier is declared and valid (QG-FED-NS-003)
  • Vocabulary provider is reachable (QG-FED-NS-004)
  • License field uses an SPDX identifier (QG-FED-NS-005)
  • At least one concept is published (QG-FED-NS-006)

Five clean runs are the bar to graduate from status: pending to status: active.

Federation Benchmark

FCC ships a federation benchmark at src/fcc/data/objectmodel/federation_benchmark.yaml that measures:

  • Concept count per namespace
  • Cross-namespace link density
  • Resolution latency
  • Conflict count

Run periodically and publish results alongside your audit evidence:

fcc evaluate federation --benchmark /tmp/fed.json

Deprecating a Namespace

Namespaces are rarely retired but occasionally a project is renamed or absorbed. The retirement protocol:

  1. Mark status: deprecated in federation_config.yaml
  2. Set sunset_date to at least 180 days in the future
  3. Ship a final release that still resolves cross-namespace queries
  4. At sunset, move the namespace to status: archived and the vocabulary becomes read-only

Deprecated namespaces remain resolvable for at least two minor-version cycles after the sunset date to avoid breaking downstream compliance evidence.