Skip to content

ADR-005: Federated KG Namespace

Date: 2026-03-29 Status: Accepted

Context

The FCC ecosystem includes 11 projects, each potentially producing its own knowledge graph (see ADR-003). When these knowledge graphs need to be queried together -- for cross-project provenance, compliance analysis, or ecosystem-wide search -- entities from different projects must be distinguishable and non-colliding.

For example, both FCC and AOME might define an entity called "privacy_classification." Without namespacing, a federated query cannot determine which project's entity is being referenced. With namespacing, fcc:privacy_classification and aome:privacy_classification are unambiguously different entities.

We evaluated three namespace approaches:

  1. Prefix-based naming convention. Prepend project abbreviations to entity IDs (e.g., fcc_research_analyst). Simple but fragile -- no formal resolution mechanism, relies on naming discipline.
  2. URN scheme. Use Uniform Resource Names (e.g., urn:fcc:persona:research_analyst). Formal but not web-dereferenceable and not standard in the RDF ecosystem.
  3. IRI-based namespaces. Use Internationalized Resource Identifiers (e.g., https://fcc.example.org/ontology/research_analyst). The RDF/OWL standard for entity naming.

Key requirements:

  • Global uniqueness across all ecosystem projects.
  • Compatibility with standard RDF tooling.
  • Support for federated queries that span multiple projects.
  • A registry mechanism for managing namespace registrations.
  • Compatibility with the pure-Python serializers from ADR-003.

Decision

We will use IRI-based namespaces with a NamespaceRegistry for federation management.

Each project owns a unique namespace IRI:

Project Namespace IRI Prefix
FCC https://fcc.example.org/ontology/ fcc:
AOME https://aome.example.org/ontology/ aome:
CONSTEL https://constel.example.org/ontology/ constel:
CTO https://cto.example.org/ontology/ cto:
Sky-Parlour https://sky-parlour.example.org/ontology/ sky:
Shared https://ecosystem.example.org/shared/ shared:

The NamespaceRegistry provides:

  • register(prefix, iri) -- register a project namespace.
  • resolve(prefixed_id) -- expand fcc:research_analyst to the full IRI.
  • compact(full_iri) -- shorten a full IRI to its prefixed form.
  • list_namespaces() -- return all registered namespaces.
  • validate_no_conflicts() -- verify that no two projects share a prefix or IRI.

The shared namespace (shared:) defines cross-cutting terms used by all projects: shared:createdAt, shared:version, shared:status, shared:owner, shared:license. These terms ensure that federated queries can join on common fields without project-specific translation.

Consequences

Positive

  • Global uniqueness. IRI-based namespaces guarantee non-collision. No two projects can accidentally use the same fully-qualified identifier.
  • RDF standard. IRIs are the standard naming mechanism in RDF and OWL. All standard RDF tools (triple stores, SPARQL engines, visualization tools) understand IRIs natively.
  • Web-dereferenceable (optional). In a web-enabled deployment, namespace IRIs can resolve to the entity's description via content negotiation. This is optional but available.
  • Registry-managed. The NamespaceRegistry provides a single point of management for all namespace registrations, preventing duplicates and enabling programmatic discovery.
  • Federated query support. Queries can span multiple namespaces. The query planner uses the registry to route sub-queries to the appropriate project's knowledge graph.
  • Serializer compatible. The pure-Python serializers from ADR-003 use prefixed names in Turtle output and full IRIs in N-Triples output, both standard representations.

Negative

  • Verbose. Full IRIs are long (https://fcc.example.org/ontology/research_analyst vs. research_analyst). Prefixed shorthand mitigates this for human readability, but storage and transmission use full IRIs.
  • Central registry dependency. The NamespaceRegistry must be shared across all projects. If it is out of sync, federation queries may fail. This introduces a coordination dependency.
  • Namespace evolution. If a project changes its namespace IRI (e.g., due to domain change), all cross-project references to that project's entities must be updated. This is a breaking change.

Mitigations

  • Turtle serialization uses prefixed shorthand for human readability. N-Triples uses full IRIs for machine processing. The format choice matches the use case.
  • The NamespaceRegistry is loaded from a version-controlled configuration file (config/namespaces.yaml). All projects in the ecosystem reference the same file. CONSTEL mediates namespace discovery for projects that do not have local access to the file.
  • Namespace IRIs are chosen once and never changed. The example.org domain in the default IRIs is a placeholder; production deployments use their organization's domain.