Property Data Trust Framework 2 Specification
v0.3 Jul 2025
Introduction {#introduction}
This specification sets out the requirements for Property Data Trust Framework (PDTF) participants to generate, exchange and verify property-related information in a secure and trusted manner.
The current focus of the PDTF is to support residential property transactions in the UK, specifically to reduce friction in the conveyancing and lending processes, which are characterised by significant re-keying of data and duplicated collection.
It is however envisaged that it will evolve to cover the full lifecycle of property and to extend to commercial property as well.
This version of the framework is an evolution of v1.0, which is already in production use across a range of industry participants, and reflects the lessons learned over the last two years of deployments. Although the existing single data schema will be split up into its component parts to model each of the entities described below, the intention is that the data will remain largely backwards-compatible with v1.0, only the provenance wrapper and exchange mechanisms being significantly different.
This spec builds on a range of existing technologies including
Our intention around the use of these existing standards is to ensure resources and tools are available for a range of implementations and to only invent new mechanisms where necessary to meet the requirements of our property and identity data use cases.
This spec should be read alongside those listed above, which contain the underlying detail to fully implement a PDTF-compliant system.
Core Technologies {#core-technologies}
Verifiable Credentials
The PDTF v2.0 uses the W3C Verifiable Credentials (VC) model to encapsulate all claims made about these entities (or relationships between them) along with human-readable evidence to support those claims, digital signatures to allow machine verification of the source of the claims and terms of use which allow access to be restricted to certain participant roles.
PDTF VCs use JSON-LD serialization to support a simpler, more human-readable syntax and to lower implementation barriers.
Uniform Resource Names
In most cases we use PDTF-namespaced Uniform Resource Name schemes that are also natural identifiers for Property (of the form urn:pdtf:uprn:12343556) or Titles (of the form urn:pdtf:title:XX1234).
However in the case of e.g. new build properties (where UPRNs may not have been allocated) or Unregistered land (which has not been allocated a title number) we can use synthetic identifiers urn:pdtf:property:ABCDE123456 or urn:pdtf:unregisteredTitle:89034ABCDE where in each case a base58-encoded UUID is used.
Or possibly urn:pdtf:property:7N22wRSnPuVwqsPkyFzY2r or urn:pdtf:propertyWithUprn:12342
And urn:pdtf:title:7N22wRSnPuVwqsPkyFzY2r or urn:pdtf:titleWithNumber:XX213
Decentralized Identifiers
All participant subjects are identified using DIDs, generated and controlled by the PDTF-compliant platform through which they are accessing the property data and associated with the user accounts on that platform. So for example a conveyancer would login to an account in their PDTF-compliant Case Management System (CMS) and that system would generate for them a DID which can be associated with the transaction as a participant.
A key benefit of this model is that identity verification performed on an individual and associated with their participant DID strongly binds the DID to that real-world identity and allows us to robustly underpin the assertions a participant makes. In practice this is likely to apply initially only to Sellers and Buyers, but the ability to bind real-world identity (and qualifications) to Conveyancers, Estate Agents etc can further enhance the robustness of the transaction.
In the future we expect to support Verifiable Legal Entity Identifiers (vLEIs) to allow organisations and their employees to assert their identities.
We also use DIDs for Transactions which allow us to verify the nexus of the transaction data (where it is being aggregated) and to support the specification of service endpoints to access it.
Importantly, the Trust Framework repository itself embeds a set of DIDs that form the roots of trust for the ecosystem. These will comprise DIDs for primary sources of data (such as, in the future, HMLR) and also trustied proxies that can be relied on to connect to non-compliant sources of data and accurately issue them as VCs into the ecosystem.
In this way all VCs can be signed and verified as having been issued by either a trusted primary source, a trusted proxy or an individual or organization which in turn can prove its real-world identity.
In practice, PDTF DIDs will normally use the did:key method (for simple participant DIDs) or did:web method (for more flexible participant DIDs or for transactions, which need to describe service endpoints). However implementers should support universal DID resolution to ensure other methods are handled.
Entities {#entities}
The PDTF incorporates a number of Entity models whose relationships connect all of the relevant aspects of the transaction.
Person
A natural person who is a participant in the transaction, who might be a Seller, Buyer, Estate Agent, Seller’s Conveyancer etc. A Person’s attributes would include their name, date of birth, residential address, email etc, and also, in respect of a Seller, the capacity in which they are selling the property (as a Legal Owner, on behalf of a deceased person etc).
All persons in the transaction participate via user accounts generated for PDTF-compliant software that act on their behalf and manage their identifiers.
The PDTF identifier for a Person is a Decentralized Identifier (DID) as described below, using for example did:key or did:web methods depending on the platform hosting their account, for example:
did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH
Organisation
An organisation who is a participant in the transaction, with any of the roles and capacities in which a Person might act. Like persons, organisations participate via user accounts (which might have multiple users per organisation) managed by PDTF-compliant software systems.
Like Person identifiers, Organisation identifiers are DIDs generated and managed by the platform that provides them access to the transaction.
Property
The property being transacted, against which we wish to record relevant attributes such as its address, Energy Performance Certificate rating, Council Tax band etc.
Property identifiers are URNs of the form
urn:pdtf:uprn:365456
Title
A verifiable ownership of a property by one or more Legal Owners (Persons or Organisations) whether or not registered at HM Land Registry. Multiple titles may be transferred during a single transaction.
All titles are related to HMLR Title Numbers, and are of the form:
urn:pdtf:title:XX123
Transaction
A Transaction represents an “intent to sell” a property (transferring one or more titles) at a given price. Relationships between the transaction and other entities forms the PDTF Graph modelling the sale and purchase of the property:
- Transaction->Person relationships identify the participants
- Transaction->Property relationships identify the property that is for sale according to the Seller’s intent.
- Transaction->Title relationships identify those Titles which are to be transferred on sale, according to the Seller’s intent
Transaction identifiers are of the form:
urn:pdtf:transaction:BsGLeLrkFdtKaMA2DphXVX
[Alternatively]Transaction identifiers must be DIDs that are resolvable to a DID document that defines a service endpoint for a service of type pdtfService and with a serviceEndpoint property that points to the API endpoint for making standard API calls. For example this DID
did:web:movetopia.com:transactions:BsGLeLrkFdtKaMA2DphXVX
Which resolves to a DID document at
https://movetopia.com/transactions/BsGLeLrkFdtKaMA2DphXVX/.well-known/did.json
Contains the following fragment:
“service”: [
{
“id”: “did:web:movetopia.com:transactions:BsGLeLrkFdtKaMA2DphXVX#pdtService”
“type”: “PdtfService”,
“serviceEndpoint”: “https://api.movetopia.com/transactions/BsGLeLrkFdtKaMA2DphXVX
}
]
A system who is aware of this transaction DID can then identify where to make API calls to retrieve VCs.
The ‘relationship graph’ formed by the connections between these entities allows us to model the entirety of the process.
PDTF Verifiable Credentials {#pdtf-verifiable-credentials}
PDTF VCs use the following features to support our security and interoperability requirements
- The PDTF VC context defines the entity schemas and policies referenced in VCs
- The id property is supplied as a URL to an accessible representation of the VC (subject to authorization controls)
- The type property is supplied as VerifiableCredential plus a PDTF-specific type that defines the entity type being represented (PersonCredential, OrganizationCredential, TitleCredential, PropertyCredential, TransactionCredential).
- The issuer property must contain the DID of the data source (trusted primary source, trusted proxy or participant.
- The validFrom property which represents the date and time that the data was originally collected (not necessarily the credential issuance date).
- An optional validUntil property which contains a natural expiry date for the claims. This is intended to model the real-world expiry of claims such as Energy Performance Certificates for example, rather than conventions around when data such as Searches are considered to be ‘acceptable’.
- A credentialSubject property which contains an id property representing the subject of the claims, together with either
- Patch paths: One or more key-value pairs representing path:value claims where the path is relative to the root of the relevant schema and which is normally used for deeply-nested Property attributes. The value object must be valid against the subschema at the supplied path and is intended to replace any existing data in a previously aggregated state at that path.
- Merge object: An object which is a valid JSON representation of the claim data in accordance with the top-level entity schema and should be merged with data in a previously aggregated state.
- VCs containing multiple credentialSubjects expressed as an array are supported, but where the sources, permissions or evidence of attributes varies, multiple credentials should be issued..
- A credentialSchema property that references the PDTF schema to validate against.
- A proof property that represents an embedded proof (digital signature) in accordance with the VC Data Integrity spec, of type DataIntegrityProof and proofPurpose of assertionMethod.
- A termsOfUse property that encapsulates access permissions for the VC and which is described in more detail below.
- An evidence property containing an array of evidence objects, as described below.
Evidence
While ideally relying parties should accept the embedded proofs supplied as sufficient evidence for the validity of the claims, in practice most parties will also need to be able to manually review underlying evidence, if only for audit purposes.
The PDTF supports Hyperlink and Vouch evidence, where:
- Hyperlinks should point to a network-accessible copy of the evidence, which may be a PDF or image, or a link to a web page from where the data was sourced. All links to web resources should be accompanied by a hashlink representation to allow verifiers to ascertain that the resource has not changed. For non-public resources, resource access should be protected by the same DID-Auth mechanism as the VCs themselves. [alternatively should be protected by OAuth authentication allowing access using the accompanying token.]
- Vouch evidence contains the name and participant role of the voucher - the human who has supplied the claims. This provides a human-readable representation of that individual and supplements the fact that the voucher is also the issuer of the credential and so has their DID represented as the issuer attribute.
Trust Model {#trust-model}
The Framework takes a two-pronged approach to trust: VCs include machine-verifiable cryptographic proofs of the provenance of data alongside human-readable evidence.
Cryptographic proofs are contained within the VC proof property and use public-private key pairs referenced in the DIDs that underpin the issuers of those VCs, whether they be natural persons (where the DID can be bound to a digital identity VC) or an organisation (where in future a vLEI can fulfil the same purpose). In this way proofs can be constructed for this wide range of participants without any centralised effort.
In the case of electronic data sources, trust is underpinned by a small number of DIDs being managed by the Trust Framework itself. These represent either the official Trusted Issuers (primary sources) of data where they are able to issue VCs themselves, or one of a number of Trusted Proxies that can accurately transform primary source data into the required format and sign those VCs themselves.
Trusted DIDs are managed by framework administrators as a simple list in the secure PDTF Trust Framework github repository.
Data consumers can then always discover the necessary public keys to verify the proofs by resolving either from the DID registry exposed by the Trust Framework or directly from the participants' DIDs themselves.
Additionally, where permissions allow, trusted participants can access the verified digital identities for e.g. Sellers and Buyers (also supplied as VCs and with the participant DID as its Subject) and make that connection into real world identity for the data supplied by them.
Security Model {#security-model}
The PDTF uses a dynamic permissions model whereby access to VCs is restricted to those participants who can prove they control their respective DIDs.
These transaction-participant relationships are themselves defined as VCs, issued initially by the participant initiating the transaction (normally the Estate Agent or a Seller) and each representing the consent of a participant to share with another.
Specifying visibility
The VC termsOfUse property represents the visibility of its contained claims with:
- A type of TrustFrameworkPolicy
- A trustFramework property of PropertyDataTrustFramework,
- A confidentialityLevel of Public, Restricted or Confidential,where Public access does not require authentication, Restricted access is limited to all of the transaction’s verified participants (see below) and Confidential is limited to participants associated with a specific subset of roles.
- A requiredCredentials property detailing the credentials with the required roles associated with them. [we might also allow specific participant DIDs to be listed here -we don’t want to share with all Conveyancers, just this one?]
- A PII property that flags whether the claims contain Personally Identifiable Information.
Interoperability {#interoperability}
Transaction nexus
The existing PDTF data exchange mechanisms are based on simple HTTP API calls and as such are easy to understand and implement.
The PDTF 2.0 model also follows this model, albeit with necessary enhancements to support the use of VCs and access controls.
In practical terms, any given transaction is hosted at a single nexus, or hub, but this might be at one of any number of PDTF-compliant servers. That nexus has the responsibility to store the relevant VCs, manage participants (expressed as relationship VCs) and control access accordingly. The API endpoint for the nominated hub is represented in the service endpoint defined in the transaction DID.
[Alternatively]
[hosting revocation lists?]
Enforcing access controls
This model necessarily requires that platforms sharing VCs have complete access to the Transaction VCs that specify the participant relationships in order to enforce access controls.
A proposed specification for a DID Auth based OAuth2 mechanism is here.
Given the authorisation process scopes the issued token to the transaction and the participants role, VCs that are returned from a /claims request can be filtered to only those that are visible to the requesting party.
By definition, access to publicly-visible VCs should be allowed even without authorisation.
In respect of new VCs being issued (POSTed) to the server, we restrict access to those DIDs that identify participants (and only accept VCs issued by those DIDs) or DIDs that are available through the Trust Framework that represent primary sources and trusted proxies (again requiring the issuer of that VC to match).
To support a peer-to-peer model it may be permissible to set up unrestricted access to receive and post VCs where we wish to replicate the VC collection between trusted systems.
To ensure consumers retain control of access to their data, peers in the network must ensure they hold a complete copy of all VCs, in particular those representing the relationships between the transaction and its participants, so that when these change the resulting authorisation changes are propagated.
Equally, non-peers (pure consumers of VCs) must not durably persist VCs beyond a minimum necessary period.
[Proposed] PDTF servers may also expose an OAuth Authorization Code endpoint where a user can demonstrate control of [either/both] an existing participant’s email address (by clicking on a verification link sent to that address) [and/or] mobile phone number (by entering a verification code sent to that number via SMS).
Credential revocation
…especially in relation to participant relationship credentials, so that the seller or buyer can control access to the data. Get vendors managing user access and relationship credentials to support e.g. VC Bitstring Status list revocation.
Implementation {#implementation}
PDTF Servers
A PDTF-compliant server must implement the following endpoints [TODO link to OpenAPI spec] using a base URL as specified in the transaction DID document service endpoint:
GET /verifiableCredentials
Returns all authorised VCs in the transaction graph
GET /state
Returns an aggregated state formed from the authorised VCs in the transaction graph, with Property, Participant and Title entities represented as top level property, participant and title properties.
POST /verifiableCredentials
Adds a VC to the collection, requiring the VC issuer to match the DID presented on authorisation.
POST /subscribe
Subscribes to changes in authorised VCs in relation to the DID presented.
DELETE /subscribe
Unsubscribes from changes.
Managing participants
Relationship vouches