as4-411/docs/architecture/data-model.md

Data Model

Canonical persistence model for the as4-411 directory. Aligned with OpenAPI schemas and the resolution algorithm.

Tables (relational baseline)

tenants

Multi-tenant isolation. All participant data is scoped by tenant.

Column	Type	Description
id	PK	Tenant identifier
name	string	Display name
created_at	timestamp
updated_at	timestamp

participants

Logical entity capable of sending/receiving messages (organization, node, service).

Column	Type	Description
id	PK	Participant identifier
tenant_id	FK	References tenants
name	string	Display name
created_at	timestamp
updated_at	timestamp

identifiers

Typed identifier bound to a participant. Used for resolution lookup and cross-mapping.

Column	Type	Description
id	PK
participant_id	FK	References participants
identifier_type	string	See Identifier types
value	string	Identifier value
scope	string	Optional scope (e.g. scheme)
priority	integer	Resolution priority (higher = preferred)
verified_at	timestamp	When value was last verified (e.g. SMP fetch)

endpoints

Routable address for a protocol domain (HTTPS URL, MLLP, MQ queue, SS7 point code, etc.).

Column	Type	Description
id	PK
participant_id	FK	References participants
protocol	string	as4, ss7, smp, http, mq, etc.
address	string	Protocol-specific address (URL, PC/SSN, queue name)
profile	string	Transport profile (e.g. AS4 profile name)
priority	integer	Ranking for resolution
status	string	active, inactive, draining

capabilities

Supported services/actions/processes/document types and constraints.

Column	Type	Description
id	PK
participant_id	FK	References participants
service	string	e.g. AS4 service value
action	string	e.g. AS4 action
process	string	e.g. PEPPOL process ID
document_type	string	e.g. document type ID
constraints_json	JSON	Additional constraints

credentials

References to key material in vault/KMS. No private keys stored in DB.

Column	Type	Description
id	PK
participant_id	FK	References participants
credential_type	string	tls, sign, encrypt
vault_ref	string	URI to vault/KMS
fingerprint	string	Certificate/key fingerprint
valid_from	timestamp
valid_to	timestamp

policies

Rules controlling resolution (tenant scope, trust domains, allow/deny, priority).

Column	Type	Description
id	PK
tenant_id	FK	References tenants
rule_json	JSON	ABAC rule definition
effect	string	allow, deny
priority	integer	Evaluation order

audit_log

Append-only audit trail for all modifications. Optional hash-chain for tamper-evidence.

Column	Type	Description
id	PK
at	timestamp
actor	string	Who made the change
action	string	create, update, delete
resource	string	tenants, participants, etc.
resource_id	string
payload	JSON	Before/after or diff
hash_prev	string	Optional: previous row hash for chain

Relationships

erDiagram
  tenants ||--o{ participants : "has"
  participants ||--o{ identifiers : "has"
  participants ||--o{ endpoints : "has"
  participants ||--o{ capabilities : "has"
  participants ||--o{ credentials : "has"
  tenants ||--o{ policies : "has"
  participants {
    string id PK
    string tenant_id FK
    string name
  }
  identifiers {
    string id PK
    string participant_id FK
    string identifier_type
    string value
    int priority
  }
  endpoints {
    string id PK
    string participant_id FK
    string protocol
    string address
    string status
  }

• Tenant scopes all participants and policies.
• Participant has many identifiers, endpoints, capabilities, and credential refs.
• Resolution uses identifiers to find participants, then endpoints + capabilities + policies to produce directives.

Graph layer (edges)

Cross-mapping and provenance are modeled as an explicit graph. An edges table (or equivalent) represents relationships with provenance and validity.

edges

Column	Type	Description
id	PK
from_type	string	Entity type (identifier, participant, etc.)
from_id	string	Source entity id
to_type	string	Target entity type
to_id	string	Target entity id
relation	string	Relation kind (e.g. resolves_to, has_endpoint)
confidence	number	0–1 confidence score
source	string	Provenance (internal, smp, gtt_feed, etc.)
valid_from	timestamp
valid_to	timestamp	Optional

Relationship types: identifier → participant (resolves_to), participant → endpoint (has_endpoint), participant → capability (has_capability). When two sources give different data for the same logical edge, conflict resolution applies.

Conflict resolution (deterministic)

When multiple candidates or edges exist, apply in order:

1. Explicit priority (from endpoint/identifier priority column)
2. Policy (allow/deny and policy priority)
3. Freshness (updated_at / verified_at / valid_from)
4. Confidence (edge or evidence confidence score)
5. Lexical (stable sort by id)

Documented in resolution-algorithm.md.

RouteDirective (output schema)

Normalized object returned by the resolver. Must match OpenAPI RouteDirective.

Field	Type	Description
target_protocol	string	e.g. as4, ss7
target_address	string	Endpoint address (URL, PC/SSN, etc.)
transport_profile	string	Profile name
security	object	signRequired, encryptRequired, keyRefs, algorithms
service_context	object	service, action, or SS7 service indicator
qos	object	retries, receiptsRequired, ordering
ttl_seconds	int	Cache TTL for this directive
evidence	object	source, lastVerified, confidenceScore

Identifier types

Reference values for identifier_type and resolution input. See protocol domains in the master plan.

AS4 domain

• as4.partyId (with optional partyIdType in scope)
• as4.role (initiator/responder)
• as4.service, as4.action, as4.mpc

For FI-to-FI, PartyId type is often BIC or LEI (see iso20022-over-as4).

PEPPOL / SMP

• peppol.participantId
• peppol.documentTypeId
• peppol.processId

SS7 domain

• e164 (MSISDN, E.164 format)
• gt (Global Title)
• pc (Point Code)
• ssn (Subsystem Number)
• mccmnc (mobile network identifiers where relevant)

Cross-mapping examples: as4.partyId: "0088:123456789" ↔ peppol.participantId: "0088:123456789"; e164 ↔ gt ↔ pc/ssn via GTT.