Architecture Overview
What is PDTF 2.0?
Section titled “What is PDTF 2.0?”PDTF 2.0 is a complete redesign of the Property Data Trust Framework. It replaces the OpenID Connect verified claims model with W3C Verifiable Credentials, decomposes the monolithic schema into an entity graph, and introduces decentralised identifiers (DIDs) and cryptographic signing.
The result: property data that is independently verifiable, portable between systems, and machine-readable by any agent or platform — without trusting the intermediary serving it.
What changed from v1
Section titled “What changed from v1”| Aspect | PDTF v1 (Current) | PDTF 2.0 |
|---|---|---|
| Data model | Monolithic pdtf-transaction.json (~4,000 paths) | Entity graph: 10 distinct entities |
| Claims | OpenID Connect verified claims with pathKey:value REPLACE semantics | W3C Verifiable Credentials with sparse objects |
| Identity | Firebase Auth UIDs, no universal identifiers | DIDs: did:key (users), did:web (transactions, adapters) |
| Entity identifiers | Internal Firestore document IDs | URNs: urn:pdtf:titleNumber:{value}, urn:pdtf:uprn:{value} |
| Verification | Trust the platform serving the data | Cryptographic proof — verify the signature, not the intermediary |
| Provenance | OIDC-derived evidence schema (deeply nested) | Simpler evidence model reflecting actual usage patterns |
| Access control | Platform-enforced role checks | Per-credential termsOfUse + participation credential presentation |
| Interoperability | REST API, platform-specific | DID documents with service endpoints, MCP-compliant API |
| Trust | Single platform trust | Federated trust via OpenID Federation (relying on Trust Anchors, Federation Entity Statements, and Property Trust Marks like title-data-provider and regulated-conveyancer) |
The entity graph
Section titled “The entity graph”PDTF 2.0 decomposes the monolithic property data pack into ten distinct entities:
| Entity | Identifier | Purpose |
|---|---|---|
| Transaction | did:web | Sale metadata, status, milestones, financial context. The root of the graph. |
| Property | urn:pdtf:uprn:{uprn} | Physical property: address, features, energy, environmental data. Everything in the “logbook”. |
| Title | urn:pdtf:titleNumber:{number} | Legal title: register extract, ownership type, leasehold terms, encumbrances. |
| Person | did:key | Natural person: name, contact details, verification status. Role-free. |
| Organisation | did:web | Legal entity: law firm, estate agency, lender. |
| SellerCapacity | URN (generated) | The capacity in which a Person or Organisation sells. Implies the Seller role. Revocable. |
| Offer | URN (generated) | A buyer’s offer: amount, status, conditions. Implies the Buyer role. |
| Gift | URN (generated) | A gift of funds towards a purchase. Implies the Giftor role. |
| Representation | URN (generated) | One party instructed by another, with the kind of representation as its role. Revocable. |
| TransactionRole | URN (generated) | A role with no more specific relationship: lender, landlord, tenant, surveyor. |
The graph is transaction-centric: the Transaction is the root, and it references associated Property, Title, Person, Organisation, and relationship entities.
This decomposition means:
- Property data travels with the property, not the transaction. When a sale falls through, the next buyer inherits verified property data.
- Each entity is independently credentialed. An EPC credential about the Property can be verified without any knowledge of the Transaction.
- Relationship entities are thin and revocable. SellerCapacity and Representation are signed assertions, not duplicated data.
Read the full entity graph specification →
Verifiable Credentials
Section titled “Verifiable Credentials”Every entity in the graph is wrapped in a W3C Verifiable Credential. A credential contains:
- The data — the entity itself (e.g. a Property with its address, EPC rating, flood risk data)
- The issuer — identified by a DID, registered in the OpenID Federation
- A cryptographic signature — proving the data came from the issuer and hasn’t been modified
- Evidence — provenance chain showing where the data came from
- Terms of use — confidentiality and access restrictions
- Status — a revocation endpoint for checking whether the credential is still valid
The credential format follows the W3C Verifiable Credentials Data Model v2.0 specification, using the eddsa-jcs-2022 cryptosuite for signatures.
Read the VC data model specification →
Decentralised Identifiers (DIDs)
Section titled “Decentralised Identifiers (DIDs)”PDTF 2.0 uses two DID methods:
did:key— for individual persons. Derived from a cryptographic key pair, self-certifying, no external resolution needed. Ideal for users who don’t control a web domain.did:web— for organisations, transactions, and adapters. Resolves to a DID document hosted at a well-known URL. Provides service endpoints for API access.
Each entity type has a specific identifier scheme:
| Entity | Identifier format |
|---|---|
| Transaction | did:web:example.com:transactions:{id} |
| Property | urn:pdtf:uprn:{uprn} |
| Title | urn:pdtf:titleNumber:{number} |
| Person | did:key:z6Mkh... |
| Organisation | did:web:smithandco.law |
Read the DID methods specification →
OpenID Federation
Section titled “OpenID Federation”The OpenID Federation answers a critical question: who is authorised to issue which types of credentials?
It’s a public, version-controlled JSON file that maps issuer DIDs to the entity types and data paths they can credential. Each entry specifies:
- The issuer’s DID
- Authorised entity:path combinations (e.g.
property:energyPerformance,title:registerExtract) - Trust level (root issuer, accredited issuer, or trusted proxy)
- Status (active, planned, deprecated, revoked)
- Proxy relationships (which root issuer a proxy is acting on behalf of)
Verifiers check the OpenID Federation as part of credential verification — confirming not just that the signature is valid, but that the issuer is authorised for this specific type of data.
Read the OpenID Federation specification →
Trust evolution
Section titled “Trust evolution”The trust model evolves through three phases:
Phase 1: Trusted proxies (current)
Section titled “Phase 1: Trusted proxies (current)”A small number of organisations act as trusted proxies. They connect to existing data sources (HMLR, search providers, EPC registers) and re-issue data as signed Verifiable Credentials. This requires no changes from data sources.
Phase 2: Independent adapters
Section titled “Phase 2: Independent adapters”Third-party organisations build and host their own adapters, each independently registered in the OpenID Federation. Multiple issuers per credential type. No single point of failure.
Phase 3: Primary source issuers
Section titled “Phase 3: Primary source issuers”Data sources (HMLR, local authorities, EPC register) issue Verifiable Credentials directly. The highest trust level, no intermediaries.
State assembly
Section titled “State assembly”For backward compatibility with existing systems, PDTF 2.0 provides bidirectional state assembly:
composeV3StateFromGraph()— assembles entity-graph credentials back into the v3 monolithic format. Existing systems continue working without modification.composeV4StateFromGraph()— assembles entity-graph credentials into the new v4 ID-keyed format.
This means adopters can consume PDTF 2.0 credentials through either the new entity-graph model or the existing v3 format during migration.
Read the state assembly specification →
Credential revocation
Section titled “Credential revocation”All credentials support revocation via W3C Bitstring Status List. Each credential includes a credentialStatus field pointing to a publicly accessible status list. Issuers can revoke credentials at any time by flipping a bit in the list.
This is particularly critical for:
- SellerCapacity credentials — when a property is sold, the previous ownership credential must be revoked
- Representation credentials — when a client changes solicitor, the old representation must be revoked
- Time-sensitive data — EPCs, search results, and other data that expires or becomes outdated
Read the credential revocation specification →
Specification suite
Section titled “Specification suite”The complete PDTF 2.0 specification is organised into focused sub-specifications:
| Spec | Title | Focus |
|---|---|---|
| 00 | Architecture Overview | Master reference, design decisions, trust model |
| 01 | Entity Graph & Schema | Entity definitions, schemas, field mapping |
| 02 | VC Data Model | Credential format, evidence, terms of use |
| 03 | DID Methods & Identifiers | did:key, did:web, URN schemes |
| 04 | OpenID Federation | Registry schema, trust levels, verification |
| 06 | Key Management | Key generation, storage, rotation |
| 07 | State Assembly | Graph composition, v3 compatibility |
| 13 | Reference Implementations | Package architecture, CLI tools |
| 14 | Credential Revocation | Bitstring Status List, revocation flows |