FIBO Integration

FIBO Integration

How the fXYZ Network integrates the Financial Industry Business Ontology (FIBO) into its Neo4j knowledge graph for entity classification, role management, and reference data.

Overview

FIBO is a formal ontology maintained by the EDM Council that defines concepts across the financial industry -- entities, instruments, roles, jurisdictions, and more. The fXYZ Network imports FIBO classes, properties, and individuals into Neo4j, then uses them as a classification backbone for organizations, legal entities, and party-role-context assignments.

The integration spans five layers:

1. Ontology import -- 3,025 FIBO classes, 1,244 properties, and 11,586 individuals stored as Neo4j nodes
2. Party-Role-Context (PRC) pattern -- FIBO-aligned identity management
3. Entity type taxonomy -- Organization types mapped to FIBO class URIs
4. Reference data -- ISO 3166 countries and ISO 4217 currencies from FIBO individuals
5. Legal entity bridge -- Connecting existing LegalEntity nodes to FIBO classification

FIBO Domains Imported

The import script loads 11 FIBO domains plus two Commons Ontology Library (CMNS) modules:

Neo4j Graph Model

Node Types

FIBO data is stored across four primary node types:

(:FiboClass {uri, localName, label, definition, domain, module})
(:FiboProperty {uri, localName, label, definition, propertyType, domain})
(:FiboIndividual {uri, localName, label, definition, domain})
(:Country {id, name, alpha2, alpha3, numericCode, region, fiboClassUri})
(:Currency {id, name, code, numericCode, minorUnit, symbol, fiboClassUri})

Relationships

(:FiboClass)-[:subClassOf]->(:FiboClass)         // Class hierarchy
(:FiboProperty)-[:DOMAIN]->(:FiboClass)           // Property domain
(:FiboProperty)-[:RANGE]->(:FiboClass)            // Property range
(:LegalEntity)-[:INSTANCE_OF]->(:FiboClass)       // Entity classification
(:LegalEntity)-[:INCORPORATED_IN]->(:Country)     // Jurisdiction link
(:Role)-[:CLASSIFIED_BY]->(:FiboClass)            // Role-to-FIBO mapping
(:Country)-[:USES_CURRENCY]->(:Currency)           // Country-currency link

Node Counts (After Import)

Party-Role-Context (PRC) Pattern

The PRC pattern is the core identity model. Every action in the system is performed by a Party acting in a Role within a Context.

The Triplet

PartyRoleContext {
  Party   -> Who is acting (Person, LegalPerson, SoftwareAgent)
  Role    -> What capacity they act in (Individual, Investor, Operator, ...)
  Context -> Where they are acting (Organization, Fund, Project, Network)
}

Agent-Party Hierarchy

Following FIBO's agent model, parties are structured as:

Agent (abstract)
  +-- Party (can enter contracts)
       +-- Person (individual human, identified by DID)
       +-- LegalPerson (corporation, LLC, DAO, etc.)
       +-- SoftwareAgent (automated systems)

Each Person node links upward: Person -[:IS_A]-> Party -[:IS_A]-> Agent

8 Reconciled Role Categories

5 Context Types

Materialized View

PRC assignments are stored as materialized PartyRoleContext nodes in Neo4j with relationships:

(assignment:PartyRoleContext)-[:HAS_PARTY]->(party:Party)
(assignment:PartyRoleContext)-[:HAS_ROLE]->(role:Role)
(assignment:PartyRoleContext)-[:HAS_CONTEXT]->(context:Context)

This denormalized structure enables efficient queries without multi-hop traversals.

Entity Type Taxonomy

Organization types form a hierarchy mapped to FIBO class URIs:

Organization (FIBO: fibo-fnd-org-org:Organization)
  +-- LegalEntity (FIBO: fibo-be-le-lp:LegalEntity)
       +-- Corporation (fibo-be-le-lp:Corporation)
       +-- LLC (fibo-be-le-lp:LimitedLiabilityCompany)
       +-- Partnership (fibo-be-le-lp:Partnership)
       +-- LLP (fibo-be-le-lp:LimitedLiabilityPartnership)
       +-- LP (fibo-be-le-lp:LimitedPartnership)
       +-- Foundation (fibo-be-le-lp:NotForProfitOrganization)
       +-- Nonprofit (fibo-be-le-lp:NotForProfitOrganization)
       +-- Government (fibo-be-ge-ge:GovernmentBody)
       +-- Trust* (fxyz:Trust)
       +-- DAO* (fxyz:DecentralizedAutonomousOrganization)
       +-- SoleProprietorship* (fxyz:SoleProprietorship)

Types marked with * use the fXYZ extension namespace (https://fxyz.network/ontology/BE/) because no direct FIBO equivalent exists. These are modeled as subclasses of FIBO's LegalEntity concept.

Entity Type to FIBO Class Mapping

The ENTITY_TYPE_TO_FIBO_CLASS mapping in legal-entity-fibo-bridge.ts connects each entity type to its FIBO class URI. When a LegalEntity is created, the bridge service:

1. Looks up the FIBO class URI for the entity type
2. Creates an INSTANCE_OF relationship to the corresponding FiboClass node
3. Builds a taxonomy path by traversing subClassOf relationships upward
4. Links to a Country node via INCORPORATED_IN for jurisdiction

Country and Currency Reference Data

Pipeline

ISO 3166/4217 standards
    |
    v
FIBO ontology individuals (FiboIndividual nodes)
    |
    v
Import script extracts + creates Country/Currency nodes
    |
    v
Neo4j Country/Currency nodes with USES_CURRENCY relationships
    |
    v
GraphQL queries: fiboCountries, fiboCurrencies, countryCurrencies
    |
    v
Frontend components (org creation wizard, jurisdiction selectors)

GraphQL Queries

# All countries (ISO 3166-1)
query { fiboCountries { id name alpha2 alpha3 numericCode region } }

# All currencies (ISO 4217)
query { fiboCurrencies { id name code numericCode minorUnit symbol } }

# Currencies used by a specific country
query { countryCurrencies(alpha2: "US") { id name code symbol } }

Client-Side Queries

The @repo/graphql package exports typed query definitions:

import {
  GET_FIBO_COUNTRIES,
  GET_FIBO_CURRENCIES,
  GET_COUNTRY_CURRENCIES
} from "@repo/graphql";

Legal Entity Bridge

The LegalEntityFiboBridge service connects the existing LegalEntity system to FIBO classification. It does not replace the LegalEntityService -- it enriches entities with FIBO metadata.

Bridge Operations

Example: Classifying an LLC in Singapore

const bridge = new LegalEntityFiboBridge();

// 1. Classify the entity
const classification = await bridge.classifyEntity(
  entityId,
  'LLC'
);
// Returns: {
//   fiboClassUri: "https://spec.edmcouncil.org/fibo/ontology/BE/LegalEntities/LegalPersons/LimitedLiabilityCompany",
//   fiboClassName: "LimitedLiabilityCompany",
//   taxonomyPath: ["Agent", "LegalEntity", "LegalPerson", "LimitedLiabilityCompany"]
// }

// 2. Link jurisdiction
const jurisdiction = await bridge.linkJurisdiction(entityId, 'SG');
// Returns: { countryName: "Singapore", countryCode: "SG", alpha3: "SGP", region: "Asia" }

Organization Creation Wizard

The org creation wizard uses FIBO classification in a 4-step flow:

Step 1: Identity

Select the party (person or existing legal entity) that will own the new organization.

Step 2: Entity Type

Choose from FIBO-classified entity types: Corporation, LLC, Partnership, LLP, LP, Foundation, Trust, DAO, Government, Nonprofit, Sole Proprietorship.

Each type displays its FIBO taxonomy path and description.

Step 3: Jurisdiction

Select the country of incorporation from FIBO-seeded Country nodes (249 countries from ISO 3166-1). The list is fetched via the fiboCountries GraphQL query.

Step 4: Review

Confirm all selections. On submission:

1. LegalEntityService.createLegalEntity() creates the entity node
2. LegalEntityFiboBridge.classifyEntity() links it to the FIBO class
3. LegalEntityFiboBridge.linkJurisdiction() links it to the Country node
4. A circle is created as the anchor circle for the new organization

FIBO Initialization

The FiboInitService handles setup for new and existing users:

On User Login

ensureUserFiboSetup(memberDid):

1. Creates a Person node (idempotent via MERGE on DID)
2. Links Person -[:IS_A]-> Party -[:IS_A]-> Agent
3. Links to existing Member node via HAS_PARTY and HAS_PERSON
4. Creates default PRC assignments:
   • Individual role in Personal context
   • Member role in fXYZ Network context

Default Seed Data

ensureDefaultData() creates 8 default roles and 3 default contexts:

Roles: Individual, Member, Investor, Company Owner, Operator, Consultant, Representative, Delegate

Contexts: Personal, fXYZ Network, Investment Club

Each role has a fiboUri property linking it to the corresponding FIBO class. The linkRolesToFiboClasses() method creates CLASSIFIED_BY relationships where FiboClass nodes exist.

Frontend Context

The FiboProvider context (packages/contexts/src/fibo-context.tsx) provides FIBO data to React components:

const {
  userContext,        // FiboUserContext (person, identities, compliance)
  activeIdentity,    // Current PartyRoleContext
  availableParties,  // All parties for the user
  availableContexts, // All contexts the user can act in
  availableRoles,    // All roles available
  roleCategories,    // Role category metadata
  switchIdentity,    // Switch active PRC assignment
  activateContext,   // Create new PRC assignment
} = useFiboContext();

Key Files

Related Documentation

• Holacracy Architecture -- Circle-based organization structure
• Knowledge Graph Ontologies -- Broader ontology usage in fXYZ
• Entity Structure -- Legal entity compliance requirements
• Neo4j Data Layer -- Database architecture