223 lines
9.4 KiB
Markdown
223 lines
9.4 KiB
Markdown
# Data Model
|
||
|
||
Canonical persistence model for the as4-411 directory. Aligned with [OpenAPI schemas](../api/openapi.yaml) and the [resolution algorithm](resolution-algorithm.md).
|
||
|
||
## 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](#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
|
||
|
||
```mermaid
|
||
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](resolution-algorithm.md).
|
||
|
||
## RouteDirective (output schema)
|
||
|
||
Normalized object returned by the resolver. Must match [OpenAPI RouteDirective](../api/openapi.yaml#components/schemas/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](../protocols/iso20022-over-as4.md)).
|
||
|
||
### 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.
|