Skip to main content

Interoperability Specification

This document defines how independent PTI v1.0 implementations achieve cross-vendor interoperability.

Normative language​

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119.

Interoperability goals​

Independent implementations MUST be able to:

  • Exchange canonical trust events without proprietary field translation.
  • Resolve pti_id references through registry federation or delegated lookup.
  • Verify signed trust assertions across operator boundaries.
  • Negotiate API and schema versions without silent incompatibility.

Conformance profiles​

A profile is a named subset of PTI requirements for a deployment class.

Profile IDAudienceRequired capabilities
pti-producer/v1Trust producersEvent ingest, idempotency, context binding
pti-consumer/v1Trust consumersLookup, verification, entitlement checks
pti-registry/v1Registry operatorsIdentity directory, merge policy, catalogs
pti-federation/v1Multi-operator fabricsSigned replication, conflict rules

Implementations MUST publish a machine-readable profile document at a well-known registry endpoint.

Protocol bindings​

The abstract APIs in Reference API Specification MAY bind to:

BindingTransportFormatStatus
HTTP+JSONHTTPSapplication/jsonREQUIRED baseline
HTTP+JSON-LDHTTPSLinked data contextsOPTIONAL
Async queueAMQP, Kafka, SQSCanonical event envelopeRECOMMENDED for high volume

All bindings MUST preserve:

  • correlation_id
  • schema_version
  • context_id
  • idempotency_key

Schema negotiation​

Clients and servers MUST support version negotiation per Versioning Strategy.

  • Servers MUST reject unsupported major versions with PTI-4001.
  • Servers SHOULD accept minor version drift when backward compatible.

Event catalog interoperability​

Producers MUST map local event types to canonical event_type values registered in the shared catalog. Custom event types MAY be used within a tenant but MUST NOT be promoted to federation without catalog registration.

Canonical event types MUST include:

{
  "event_type": "lending.repayment.completed",
  "context_id": "lending",
  "schema_version": "trust_event.v1",
  "payload_schema": "https://schemas.pti.example/trust_event/lending_repayment/v1"
}

Trust assertion exchange​

Cross-operator assertion exchange MUST use signed envelopes:

FieldRequirement
assertion_idGlobally unique UUID
issuerRegistry-trusted producer URI
subject_pti_idResolved portable identifier
context_idRegistered context
issued_atISO 8601 UTC
signatureJWS or COSE per security profile

Verifiers MUST validate signature, expiration, and issuer trust chain before ingesting foreign assertions.

Registry federation​

Federated registries MUST:

  • Reconcile pti_id conflicts using published merge precedence rules.
  • Propagate subject suppression and erasure requests.
  • Maintain eventual consistency with maximum divergence window declared in SLA (default: 15 minutes).

Error interoperability​

All implementations MUST map internal failures to Reference Error Codes. Custom error namespaces MUST NOT replace standard codes for equivalent conditions.

Conformance testing​

Operators SHOULD maintain test suites covering:

  1. Golden-path event ingest and lookup
  2. Idempotent replay
  3. Version mismatch handling
  4. Authorization denial paths
  5. Federation assertion verify/reject

Third-party auditors MAY certify profile conformance; certification MUST NOT imply regulatory approval.