#5. CP Registry, Master Registry, and Directory

Connected Services Framework (CSF) — Part 1: Framework — Version 2.0

#5.1 Overview

The distributed registry model is a foundational pillar of the CSF. Unlike a centralised model where a single operator maintains the master list of all CPs, the CSF distributes this responsibility across all MAPs using a three-tier approach.

Each MAP:

1. Publishes a CP Registry — a JSON document listing its own CPs and their metadata, made available to other MAPs via an OAuth 2.0-protected API endpoint
2. Collects all other MAPs' CP Registries — via those same API endpoints
3. Converges these into a Master Registry — a private, consolidated view containing full routing, PKI, and contact details for all CPs across the entire CSF network
4. Derives a Directory for its CPs — a filtered, cut-down version of the Master Registry listing just the brand names and RCPIDs available to switch with

#How the Three Tiers Work Together

1. A CP selects a destination brand from the Directory (e.g., a drop-down list in the MAP's portal)
2. The MAP uses the selected RCPID to look up the full routing and signing details in its private Master Registry
3. The Master Registry tells the MAP which MAP serves the destination CP, which endpoint to send to, and which PKI domain to use for verification
4. The destination CP's details originally came from that MAP's CP Registry, which was collected and converged into the Master Registry

#5.2 CP Registry Structure

Each MAP's CP Registry contains two main sections:

#MAP Section

Comprehensive metadata about the MAP itself:

• Identity: MAP name, version timestamp
• Contact information: Phone, email, URL with availability hours and days
• Connectivity: CP Registry API endpoint URL, OAuth token URL, messaging service endpoints
• Routing groups: Which message types (e.g., businessSwitch.*, residentialSwitch.*) are accepted at which endpoint
• Connections: List of other MAPs this MAP has established connectivity with
• Registration URI: Where new CPs or MAPs can apply to register
• Service status: URL and API endpoint for checking operational status and planned changes

#CP List Section

For each CP registered with the MAP:

• RCPID: The CP's unique identifier (UUIDv4)
• Brand name: The human-readable name shown in search/drop-down lists
• Process support: Which industry processes the CP participates in (OTS, SforB) and their status (ACTIVE, SUSPENDED, TEST)
• Resources: Customer assist URLs, sales assist URLs, switch support contacts — backward compatible with OTS resource fields
• Signing information: The DNS domain used for PKI key lookup and which routing IDs should be signed with that domain
• Contact details (optional): A contact array using the same structure as the MAP contact object — phone, email, URL with availability hours, days, and purpose (sales, support, technical). This allows each CP to advertise its own preferred contact methods for operational escalations, independent of the MAP's contacts

For the full JSON schema and field reference, see Part 2: Directory API.

#5.3 CP Registry Synchronisation

MAPs retrieve other MAPs' CP Registries via HTTP GET requests to each MAP's registry API endpoint, authenticated with OAuth 2.0 credentials established during onboarding.

#Frequency

• There is no mandatory synchronisation interval — MAPs can pull as frequently as needed
• A maximum frequency of approximately 60 seconds is recommended to avoid unnecessary load
• MAPs MUST retrieve CP Registries regularly and in near-real time, particularly as new CPs are onboarded continuously throughout the day

#Building the Master Registry

Each MAP independently converges the collected CP Registries into its own private copy of the Master Registry. The Master Registry contains:

• Full routing information: Endpoint URLs, OAuth token URLs, and routing group definitions for every MAP
• PKI signing domains: The DNS domains used for DKIM signature verification for every CP
• Contact details: MAP and CP contact information for operational support and escalations
• Service status: Real-time availability indicators for each MAP

#Deriving the Directory

From the Master Registry, each MAP creates a Directory for its own CPs. The Directory contains only the information CPs need to address messages:

• Brand names and RCPIDs — for drop-down lists and search-as-you-type
• Supported processes — which CPs support OTS, SforB, etc.
• Resource URLs — customer assist and sales assist URLs (backward compatible with OTS)

The Directory excludes inter-MAP routing details, PKI signing domains, OAuth endpoints, and other sensitive operational information. How the MAP presents the Directory to its CPs (portal, API, BSS integration) is the MAP's commercial decision.

#5.4 Advantages of the Distributed Model

#5.5 Conflict Resolution

When a CP appears in more than one MAP's CP Registry simultaneously (typically during a CP transition between MAPs), the conflict is resolved using DNS:

1. The MAP performs a DNS lookup on the CP's _mapkey record
2. The DNS record indicates the CP's current MAP endpoint
3. The MAP routes messages to the MAP indicated by DNS, regardless of which CP Registry listed the CP
4. The MAP marks the conflicting entry as being in "conflict" in its Master Registry

This DNS-based resolution ensures that the CP — not the MAP — has ultimate control over routing.

For detailed conflict resolution procedures, see Part 2: CP Transitions.

#5.6 TOTSCo Compatibility

The CSF CP Registry structure is backward compatible with the TOTSCo OTS directory. The same fields used in OTS (RCPID, brand name, customer assist URL, sales assist URL) are preserved in the CSF CP Registry using the same structure.

TOTSCo can collect CSF MAPs' CP Registries and either merge them into its own Master Registry or maintain them separately. The CP Registry is JSON-formatted, making convergence straightforward.

For details on consuming the TOTSCo Directory API, see Part 2: TOTSCo Integration. The TOTSCo Hub API Specification v2.0 defines the standard directory and letterbox interfaces used by TOTSCo and supported by the CSF for hub interoperability.