Skip to main content

Interoperability Rules

Rules ensuring independent PTI implementations exchange data and serve consumers predictably. Primary normative references: RFC-004, RFC-006, RFC-010.

API interoperability​

URL and versioning​

  • Public REST APIs MUST use /v{major}/ prefix (e.g., /v1/reports/generate).
  • OpenAPI 3.1 document MUST be published at stable URL.
  • Error responses MUST use consistent JSON envelope:
{
  "error": "context_not_entitled",
  "message": "Human-readable description",
  "details": { }
}

Required operations​

Any implementation claiming PTI compatibility MUST implement:

OperationInterop critical fields
subjects.searchcandidates[].pti_id, confidence
reports.generatereport_id, trust_evidence, schema_version
reports.getImmutable content hash match on repeat

Optional but interoperable when enabled​

OperationRule
reports.verifyMust validate RFC-012 signatures cross-vendor
contexts.listMust return RFC-002 catalogue subset
Federation /.well-known/pti-federationMust match RFC-006 schema

Schema interoperability​

Postel's law​

  • Senders MUST conform to published schema for their catalogue version.
  • Receivers MUST ignore unknown optional fields.
  • Receivers MUST reject unknown required fields in their major version.

Identifiers​

IdentifierFormatInterop rule
pti_idpti_[a-z0-9]{8,32}Never embed national ID
context_idRFC-002 catalogueNo private interchange IDs
event_typeCatalogue stringDocument in OpenAPI + catalogue
report_idOpaque stringGlobally unique per operator
manifest_idOpaque stringReferenced in verify + PRL

Context interoperability​

  • Producers on different implementations MUST use same context_id for same life area.
  • Lens contexts MUST NOT accept direct events at any implementation.
  • Disabled context MUST fail with context_not_enabled (not generic 500).

Evidence interoperability​

Cross-vendor verification MUST succeed when:

  1. Manifest schema_version is supported by verifier
  2. kid exists in issuer JWKS
  3. Signature validates on JCS-canonicalized JSON
  4. manifest_id not on PRL

Verifier MUST NOT require proprietary SDK.

Federation interoperability​

Package exchange​

RuleDetail
Profile negotiationBilateral agreement declares manifest_only or richer
Signature algorithmEd25519 or RSA-3072+ only for interop
Foreign PTI-IDpti_local@operator_id format mandatory
AttributionCombined lookup labels origin_operator_id per slice
FailureInvalid package omitted from scores (fail closed)

JWKS​

{
  "keys": [
    {
      "kid": "op_example_2026",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "..."
    }
  ]
}

Operators MUST support HTTPS JWKS fetch with cache ≤ 24h.

Event catalogue interoperability​

Shared vertical catalogues SHOULD use common event_type strings:

event_typecontext_idInterop payload fields
loan_repaymentlendingamount_minor, currency, status
lease_completedrentallease_id, status
employment_verifiedemploymentemployer_ref, role, verified_at

Custom events MAY exist locally but MUST NOT be assumed by foreign consumers.

Edge sync interoperability​

Edge nodes MUST upload pti.exchange.v1 packages with:

  • origin_operator_id of hub
  • Edge-generated report_id registered on hub after sync
  • Conflict metadata for duplicate idempotency_key

Hub MUST acknowledge with sync_receipt_id.

Version negotiation​

ScenarioBehavior
Client sends Accept-Version: 1Server responds v1 schema
Unknown major in packageverification_status: invalid
Deprecated endpointDeprecation + Sunset headers

Conformance testing for interop​

Before federation go-live:

  1. Run Category F tests (conformance-tests)
  2. Cross-verify sample manifests with partner JWKS
  3. Execute dual ingest → dual lookup → evidence verify round-trip

Anti-patterns breaking interop​

PatternImpact
Custom context IDs in federationPartner cannot map scores
Unsigned reportsVerification fails cross-vendor
Mutating report_id contentAudit hash mismatch
Proprietary error codes onlyClient cannot handle uniformly
Skipping schema_versionVerifier cannot parse