@pdtf/schemas 3.6.0-dev.30 → 3.6.0-dev.32

package/docs/v4-mapping-and-recomposition.md

@@ -343,6 +343,63 @@ transaction already carries the titles to be sold. It is emitted for **every**
 seller, whether or not a capacity has been declared, so the credential embodying
 the Seller role is never missing while a form is still being filled in.
 
+## Property–Title links
+
+`PropertyTitleLink` is the one relationship credential that references no
+Transaction (spec 01 D34). It says a UPRN is related to a title, as at a date,
+on a stated basis:
+
+```jsonc
+{ "id": "urn:pdtf:propertyTitleLink:ptl-1",
+  "property": "urn:pdtf:uprn:100023456789",
+  "title": "urn:pdtf:titleNumber:AB10000",
+  "basis": { "type": "Register Dataset",
+             "dataset": "HMLR Title Number and UPRN Look Up",
+             "asOf": "2026-10-01" } }
+```
+
+The relationship is many-to-many. A flat's UPRN can sit on its lease and on the
+block freehold, and the block freehold covers every flat in the block. The link
+is standing, so it is issued once for the UPRN and title and reused by every
+sale, not reissued for each one.
+
+**HMLR asserts, the seller selects.** The links say which titles a UPRN sits
+on. `Transaction.titlesToBeSold` says which of those are being conveyed. A
+linked title the transaction does not select is related but not sold, so no
+extra field is needed for it. `linkedTitles()` (exported as `v4LinkedTitles`)
+computes this:
+
+```js
+const { v4LinkedTitles } = require("@pdtf/schemas");
+
+v4LinkedTitles({ property, links, transaction, titles });
+// { linked, sold, relatedNotSold, unlinkedSold, superseded, awaitingRegisterLink }
+```
+
+`unlinkedSold` lists titles being sold with no link behind them. That is how a
+missing link shows up, and the conveyancer reports it to HMLR. A wrong link
+needs no handling: the seller does not select it.
+
+**One issuer per fact.** Registration status decides who issues a link.
+HM Land Registry issues it for a registered title (`urn:pdtf:titleNumber:*`, on
+`Register Dataset`). The seller's conveyancer issues it for unregistered land
+(`urn:pdtf:unregisteredTitle:*`, on `Epitome of Title`), which HMLR holds
+nothing about. The schema ties `basis` to the title's URN scheme. The trust
+framework checks who the issuer is, because a credential subject cannot vouch
+for its own signer.
+
+**First registration.** The Title issued on first registration lists the
+unregistered URN in `alsoKnownAs`. Links and selections that name the old URN
+resolve to the new title number. Once HMLR issues a link from the same UPRN to
+that number, it supersedes the conveyancer's link. Until then the conveyancer's
+link stays in force and the title is listed in `awaitingRegisterLink`.
+
+Neither direction of the round trip touches these links. V3 records no
+UPRN-to-title link, so `decompose` does not invent one and `recompose` ignores
+any it is given. The manifest lists the link as `kind: "credential"`,
+`scope: "standing"`. The five transaction-scoped credentials are listed with
+`scope: "transaction"`.
+
 ### If you want an identifier everyone can mint
 
 Three patterns, of which V3 already uses two:

package/index.js

@@ -829,6 +829,7 @@ const {
   identifyV3Pointer,
   resolveV3Pointer,
   resolveV3PointerAll,
+  linkedTitles: v4LinkedTitles,
 } = require("./src/utils/v4");
 
 module.exports = {
@@ -861,4 +862,5 @@ module.exports = {
   identifyV3Pointer,
   resolveV3Pointer,
   resolveV3PointerAll,
+  v4LinkedTitles,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdtf/schemas",
-  "version": "3.6.0-dev.30",
+  "version": "3.6.0-dev.32",
   "description": "Property Data Trust Framework Schemas and Utilities",
   "main": "index.js",
   "files": [

package/src/schemas/v3/combined.json

@@ -6770,10 +6770,15 @@
                                           "Not applicable"
                                         ],
                                         "ta7ed5Enum": [
+                                          "Managing Agent",
                                           "Landlord",
                                           "Management Company",
+                                          "Not applicable",
                                           "Other"
-                                        ]
+                                        ],
+                                        "ta7ed5EnumNames": {
+                                          "Managing Agent": "Yes"
+                                        }
                                       }
                                     },
                                     "discriminator": {

package/src/schemas/v3/overlays/ta7ed5.json

@@ -380,8 +380,17 @@
                                         "ta7ed5Ref": "4.3.2",
                                         "title": "Who collects the ground rent?",
                                         "enum": [
+                                          "Managing Agent",
                                           "Landlord",
                                           "Management Company",
+                                          "Not applicable",
+                                          "Other"
+                                        ],
+                                        "enumNames": [
+                                          "Yes",
+                                          "Landlord",
+                                          "Management Company",
+                                          "Not applicable",
                                           "Other"
                                         ]
                                       }

package/src/schemas/v4/Gift.json

@@ -6,10 +6,10 @@
   "description": "A gift of funds towards a purchase, made by a giftor. Implies the Giftor role.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "id": {

package/src/schemas/v4/Offer.json

@@ -6,10 +6,10 @@
   "description": "An offer made by a prospective buyer in a property transaction.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "id": {

package/src/schemas/v4/Organisation.json

@@ -6,10 +6,10 @@
   "description": "A legal entity (company, firm, partnership) participating in a property transaction.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "id": {

package/src/schemas/v4/Person.json

@@ -6,10 +6,10 @@
   "description": "A natural person participating in a property transaction — name, contact details, address, verification status.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "name": {

package/src/schemas/v4/Property.json

@@ -6,10 +6,10 @@
   "description": "Physical and environmental facts about a property — address, construction, fixtures, services, searches, documents. Excludes ownership, titles, and participants.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "address": {

package/src/schemas/v4/PropertyTitleLink.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://trust.propdata.org.uk/schemas/v4/entities/propertyTitleLink.json",
+  "type": "object",
+  "title": "Property–Title Link Entity",
+  "description": "A standing assertion that a property (UPRN) is related to a title. Many-to-many: one UPRN can sit on several titles, and one title (a block freehold, say) can cover many UPRNs. Issued by HM Land Registry for a registered title, and by the seller's conveyancer, on the epitome of title, for unregistered land. References no Transaction: a Transaction selects the titles being sold from the linked titles through titlesToBeSold, and a linked title it does not select is related but not sold.",
+  "x-pdtf-source": {
+    "packageName": "@pdtf/schemas",
+    "packageVersion": "3.6.0-dev.32",
+    "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
+    "combinedPath": "src/schemas/v3/combined.json",
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
+  },
+  "properties": {
+    "id": {
+      "title": "Property–Title Link URN",
+      "description": "Uniform Resource Name identifier for the link, urn:pdtf:propertyTitleLink:{id}",
+      "type": "string",
+      "pattern": "^urn:[a-z0-9][a-z0-9-]{0,31}:[a-zA-Z0-9._~:/?#\\[\\]@!$&'()*+,;=-]+$"
+    },
+    "property": {
+      "title": "Property Reference",
+      "description": "URN referencing the Property entity, urn:pdtf:uprn:{uprn}",
+      "type": "string",
+      "pattern": "^urn:[a-z0-9][a-z0-9-]{0,31}:[a-zA-Z0-9._~:/?#\\[\\]@!$&'()*+,;=-]+$"
+    },
+    "title": {
+      "title": "Title Reference",
+      "description": "URN referencing the Title entity: urn:pdtf:titleNumber:{number} for a registered title, urn:pdtf:unregisteredTitle:{id} for unregistered land",
+      "type": "string",
+      "pattern": "^urn:[a-z0-9][a-z0-9-]{0,31}:[a-zA-Z0-9._~:/?#\\[\\]@!$&'()*+,;=-]+$"
+    },
+    "basis": {
+      "title": "Basis of the link",
+      "description": "What the link rests on, and the date it speaks as at. A registered title is linked on the register's own UPRN-to-title data; unregistered land on the epitome of title.",
+      "type": "object",
+      "properties": {
+        "type": {
+          "title": "Basis type",
+          "type": "string",
+          "enum": [
+            "Register Dataset",
+            "Epitome of Title"
+          ]
+        },
+        "asOf": {
+          "title": "As at",
+          "description": "The date the link speaks as at: the dataset's effective date, or the date the epitome was examined",
+          "type": "string",
+          "format": "date"
+        }
+      },
+      "required": [
+        "type",
+        "asOf"
+      ],
+      "discriminator": {
+        "propertyName": "type"
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "Register Dataset"
+              ]
+            },
+            "dataset": {
+              "title": "Dataset",
+              "description": "The register dataset the link is taken from, e.g. \"HMLR Title Number and UPRN Look Up\"",
+              "type": "string"
+            },
+            "datasetRelease": {
+              "title": "Dataset release",
+              "description": "The release the link is taken from, e.g. the full-file name of HMLR's monthly release (\"LR_UPRN_FULL_APR.csv\"). The dataset records no date per row, so asOf is the release date.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "dataset"
+          ]
+        },
+        {
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "Epitome of Title"
+              ]
+            },
+            "rootOfTitle": {
+              "title": "Root of title",
+              "description": "The good root of title the epitome starts from",
+              "type": "object",
+              "properties": {
+                "description": {
+                  "title": "Description",
+                  "description": "e.g. \"Conveyance on sale\"",
+                  "type": "string"
+                },
+                "date": {
+                  "title": "Date",
+                  "description": "Date of the root document",
+                  "type": "string",
+                  "format": "date"
+                }
+              }
+            },
+            "epitomeDigest": {
+              "title": "Epitome digest",
+              "description": "SHA-256 digest of the epitome of title as examined, in the form sha256:{hex} (spec 02 §6.6)",
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$"
+            }
+          },
+          "required": [
+            "rootOfTitle"
+          ]
+        }
+      ]
+    }
+  },
+  "required": [
+    "property",
+    "title",
+    "basis"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "title": {
+            "type": "string",
+            "pattern": "^urn:pdtf:titleNumber:"
+          }
+        },
+        "required": [
+          "title"
+        ]
+      },
+      "then": {
+        "properties": {
+          "basis": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "Register Dataset"
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "title": {
+            "type": "string",
+            "pattern": "^urn:pdtf:unregisteredTitle:"
+          }
+        },
+        "required": [
+          "title"
+        ]
+      },
+      "then": {
+        "properties": {
+          "basis": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "Epitome of Title"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/src/schemas/v4/Representation.json

@@ -6,10 +6,10 @@
   "description": "A professional representation relationship — one party instructed by another, e.g. a conveyancer acting for a seller. One entity per (representative, represented party) pair: a conveyancer instructed jointly by two sellers yields two, and sellers who instruct separate conveyancers yield one each.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "id": {

package/src/schemas/v4/SellerCapacity.json

@@ -6,10 +6,10 @@
   "description": "The legal capacity in which a seller is selling a given title. Derived from the V3 participants 'Seller' branch (sellersCapacity, dateBecameOwnerOrAuthority).",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "id": {

package/src/schemas/v4/Title.json

@@ -6,10 +6,10 @@
   "description": "HM Land Registry title — register extract, tenure type, and legal interest details for a single title number.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "titleNumber": {
@@ -11184,10 +11184,15 @@
                         "Not applicable"
                       ],
                       "ta7ed5Enum": [
+                        "Managing Agent",
                         "Landlord",
                         "Management Company",
+                        "Not applicable",
                         "Other"
-                      ]
+                      ],
+                      "ta7ed5EnumNames": {
+                        "Managing Agent": "Yes"
+                      }
                     }
                   },
                   "discriminator": {
@@ -14655,6 +14660,16 @@
       "description": "Uniform Resource Name identifier for the title",
       "type": "string",
       "pattern": "^urn:[a-z0-9][a-z0-9-]{0,31}:[a-zA-Z0-9._~:/?#\\[\\]@!$&'()*+,;=-]+$"
+    },
+    "alsoKnownAs": {
+      "title": "Also Known As",
+      "description": "Earlier identifiers for this title — on first registration, the urn:pdtf:unregisteredTitle:{id} it was known by before a title number was issued.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^urn:[a-z0-9][a-z0-9-]{0,31}:[a-zA-Z0-9._~:/?#\\[\\]@!$&'()*+,;=-]+$"
+      },
+      "uniqueItems": true
     }
   }
 }

package/src/schemas/v4/Transaction.json

@@ -6,10 +6,10 @@
   "description": "Transaction-level metadata — status, milestones, chain, contracts, offers, enquiries, and sale context.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "transactionId": {

package/src/schemas/v4/TransactionRole.json

@@ -6,10 +6,10 @@
   "description": "A party's role in a transaction, where no more specific relationship credential applies. Asserts participation in a role, not a relationship to another named party.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "properties": {
     "id": {

package/src/schemas/v4/mapping.json

@@ -5,10 +5,10 @@
   "generator": "src/utils/generateV4Schemas.js",
   "source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.30",
+    "packageVersion": "3.6.0-dev.32",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "4e95946a946b37088b153052034fd0584cc27a6eb53f78ede52cd0ab1fde669f"
+    "combinedSha256": "83f31fddf82e57e67f2bc92844459095041b254b970d8881dd4318248c188f67"
   },
   "entities": {
     "Property": {
@@ -39,27 +39,38 @@
     "Representation": {
       "$id": "https://trust.propdata.org.uk/schemas/v4/entities/representation.json",
       "kind": "credential",
-      "idScheme": "did"
+      "scope": "transaction",
+      "idScheme": "urn"
     },
     "TransactionRole": {
       "$id": "https://trust.propdata.org.uk/schemas/v4/entities/transactionRole.json",
       "kind": "credential",
-      "idScheme": "did"
+      "scope": "transaction",
+      "idScheme": "urn"
     },
     "Gift": {
       "$id": "https://trust.propdata.org.uk/schemas/v4/entities/gift.json",
       "kind": "credential",
-      "idScheme": "did"
+      "scope": "transaction",
+      "idScheme": "urn"
     },
     "SellerCapacity": {
       "$id": "https://trust.propdata.org.uk/schemas/v4/entities/sellerCapacity.json",
       "kind": "credential",
-      "idScheme": "did"
+      "scope": "transaction",
+      "idScheme": "urn"
     },
     "Offer": {
       "$id": "https://trust.propdata.org.uk/schemas/v4/entities/offer.json",
       "kind": "credential",
-      "idScheme": "did"
+      "scope": "transaction",
+      "idScheme": "urn"
+    },
+    "PropertyTitleLink": {
+      "$id": "https://trust.propdata.org.uk/schemas/v4/entities/propertyTitleLink.json",
+      "kind": "credential",
+      "scope": "standing",
+      "idScheme": "urn"
     }
   },
   "roundTrip": {
@@ -74,7 +85,7 @@
       "Gift",
       "TransactionRole"
     ],
-    "note": "All of these are required to reconstruct a V3 instance. The credentials are not redundant copies: role and every relationship live only on them, so that revoking a credential removes what it asserts rather than leaving a second copy on the transaction. Organisation is the one entity outside the round trip.",
+    "note": "All of these are required to reconstruct a V3 instance. The credentials are not redundant copies: role and every relationship live only on them, so that revoking a credential removes what it asserts rather than leaving a second copy on the transaction. Organisation and PropertyTitleLink are outside the round trip: V3 records a participant's firm only as free text, and records no UPRN-to-title link at all, so decompose does not invent either and recompose does not need them.",
     "roleImpliedByCredential": {
       "SellerCapacity": "Seller",
       "Offer": "Buyer",
@@ -874,6 +885,22 @@
       "notes": "An offer in Transaction.offers that no participant references stays transaction data and yields no credential, since Offer requires a buyer."
     }
   },
+  "standingCredentials": {
+    "PropertyTitleLink": {
+      "description": "A standing UPRN-to-title link. Not projected from V3. A Transaction's titlesToBeSold selects the titles being sold from the titles linked to its property; see linkedTitles() in src/utils/v4.js.",
+      "issuerByTitleScheme": {
+        "urn:pdtf:titleNumber:": {
+          "issuer": "HM Land Registry",
+          "basis": "Register Dataset"
+        },
+        "urn:pdtf:unregisteredTitle:": {
+          "issuer": "Seller's conveyancer",
+          "basis": "Epitome of Title"
+        }
+      },
+      "supersession": "On first registration the Title for the new title number lists the unregistered URN in alsoKnownAs. An HMLR link from the same UPRN to that title supersedes the conveyancer's link to the unregistered URN; the conveyancer's link stays in force until one exists."
+    }
+  },
   "collisions": [
     {
       "key": "titleNumber",

package/src/utils/generateV4Schemas.js

@@ -20,6 +20,9 @@
  *   SellerCapacity  — legal capacity of a seller against a title (derived from
  *                     the V3 participants "Seller" oneOf branch)
  *   Offer           — buyer offer against a transaction
+ *   PropertyTitleLink — standing UPRN↔title relationship (HMLR for registered
+ *                     titles, the seller's conveyancer for unregistered land);
+ *                     the one credential that references no Transaction
  *
  * The run also emits src/schemas/v4/mapping.json — the machine-readable V3⇄V4
  * pointer mapping consumed by src/utils/v4.js.  See
@@ -203,6 +206,26 @@ const CREDENTIAL_ENTITIES = [
  * role as their own discriminator: "what kind of representation is this" is a
  * property of the representation, not a duplicated participant attribute.
  */
+/**
+ * Standing credentials: assertions that are true independently of any sale, so
+ * they reference no Transaction (D32 as narrowed by D34 in spec 01).
+ *
+ * PropertyTitleLink says "this UPRN is related to this title". For a registered
+ * title HM Land Registry is the only issuer; for unregistered land, which HMLR
+ * holds nothing about, the seller's conveyancer issues it on the strength of the
+ * epitome of title. The two cases never overlap, so there is one issuer per
+ * fact. The seller *selects* from these links via Transaction.titlesToBeSold; a
+ * linked title that is not selected is related but not sold.
+ *
+ * V3 records no such link — it has one propertyPack and the titles being sold,
+ * nothing about which titles HMLR relates to the UPRN — so these are outside the
+ * round trip: decompose does not invent them and recompose does not need them.
+ */
+const STANDING_CREDENTIAL_ENTITIES = ["PropertyTitleLink"];
+
+/** Entities whose identifier is a DID; every other entity is a URN. */
+const DID_ENTITIES = ["Transaction", "Person", "Organisation"];
+
 const ROLE_IMPLIED_BY_CREDENTIAL = {
   SellerCapacity: "Seller",
   Offer: "Buyer",
@@ -359,6 +382,19 @@ const generateTitle = () => {
     "Uniform Resource Name identifier for the title"
   );
 
+  // First registration (spec 01 §9.1 Q5): the Title issued on registration is
+  // keyed by its new title number and lists the unregistered identifier it
+  // replaces, so links and transactions that name the old URN still resolve.
+  // Not in V3, so never emitted by decompose.
+  titleItemProps.alsoKnownAs = {
+    title: "Also Known As",
+    description:
+      "Earlier identifiers for this title — on first registration, the urn:pdtf:unregisteredTitle:{id} it was known by before a title number was issued.",
+    type: "array",
+    items: { type: "string", pattern: URN_PATTERN },
+    uniqueItems: true,
+  };
+
   const required = [
     ...new Set([
       ...(pp.titlesToBeSold.items.required || []),
@@ -839,6 +875,149 @@ const generateOffer = () => {
   );
 };
 
+const generatePropertyTitleLink = () => {
+  // Hand-authored: V3 has nothing to derive it from.  The first relationship
+  // credential with no `transaction` — it is standing, true of the UPRN and
+  // the title whether or not either is being sold (spec 01 D34).
+  //
+  // `basis` is part of what is asserted, not just how the issuer came by it:
+  // HMLR's UPRN-to-title data is neither complete nor wholly accurate, so a
+  // link is only ever "related as at this date, according to this source".
+  // How the issuer obtained it goes in the credential's own `evidence`
+  // (spec 02 §6) as usual.
+  const REGISTER = "Register Dataset";
+  const EPITOME = "Epitome of Title";
+  const dateField = (title, description) => ({
+    title,
+    description,
+    type: "string",
+    format: "date",
+  });
+
+  const schema = makeSchema(
+    "propertyTitleLink",
+    "Property–Title Link Entity",
+    "A standing assertion that a property (UPRN) is related to a title. Many-to-many: one UPRN can sit on several titles, and one title (a block freehold, say) can cover many UPRNs. Issued by HM Land Registry for a registered title, and by the seller's conveyancer, on the epitome of title, for unregistered land. References no Transaction: a Transaction selects the titles being sold from the linked titles through titlesToBeSold, and a linked title it does not select is related but not sold.",
+    {
+      id: urnRef(
+        "Property–Title Link URN",
+        "Uniform Resource Name identifier for the link, urn:pdtf:propertyTitleLink:{id}"
+      ),
+      property: urnRef(
+        "Property Reference",
+        "URN referencing the Property entity, urn:pdtf:uprn:{uprn}"
+      ),
+      title: urnRef(
+        "Title Reference",
+        "URN referencing the Title entity: urn:pdtf:titleNumber:{number} for a registered title, urn:pdtf:unregisteredTitle:{id} for unregistered land"
+      ),
+      basis: {
+        title: "Basis of the link",
+        description:
+          "What the link rests on, and the date it speaks as at. A registered title is linked on the register's own UPRN-to-title data; unregistered land on the epitome of title.",
+        type: "object",
+        properties: {
+          type: {
+            title: "Basis type",
+            type: "string",
+            enum: [REGISTER, EPITOME],
+          },
+          asOf: dateField(
+            "As at",
+            "The date the link speaks as at: the dataset's effective date, or the date the epitome was examined"
+          ),
+        },
+        required: ["type", "asOf"],
+        discriminator: { propertyName: "type" },
+        oneOf: [
+          {
+            properties: {
+              type: { type: "string", enum: [REGISTER] },
+              dataset: {
+                title: "Dataset",
+                description:
+                  "The register dataset the link is taken from, e.g. \"HMLR Title Number and UPRN Look Up\"",
+                type: "string",
+              },
+              datasetRelease: {
+                title: "Dataset release",
+                description:
+                  "The release the link is taken from, e.g. the full-file name of HMLR's monthly release (\"LR_UPRN_FULL_APR.csv\"). The dataset records no date per row, so asOf is the release date.",
+                type: "string",
+              },
+            },
+            required: ["dataset"],
+          },
+          {
+            properties: {
+              type: { type: "string", enum: [EPITOME] },
+              rootOfTitle: {
+                title: "Root of title",
+                description:
+                  "The good root of title the epitome starts from",
+                type: "object",
+                properties: {
+                  description: {
+                    title: "Description",
+                    description: "e.g. \"Conveyance on sale\"",
+                    type: "string",
+                  },
+                  date: dateField("Date", "Date of the root document"),
+                },
+              },
+              epitomeDigest: {
+                title: "Epitome digest",
+                description:
+                  "SHA-256 digest of the epitome of title as examined, in the form sha256:{hex} (spec 02 §6.6)",
+                type: "string",
+                pattern: "^sha256:[0-9a-f]{64}$",
+              },
+            },
+            required: ["rootOfTitle"],
+          },
+        ],
+      },
+    },
+    ["property", "title", "basis"]
+  );
+
+  // One issuer per fact, decided by registration status: a registered title is
+  // linked on the register, unregistered land on the epitome. The schema
+  // enforces the basis; the issuer (HMLR, or a conveyancer) is checked through
+  // the trust framework, since a credential subject cannot name its own signer.
+  schema.allOf = [
+    {
+      if: {
+        properties: { title: { type: "string", pattern: "^urn:pdtf:titleNumber:" } },
+        required: ["title"],
+      },
+      then: {
+        properties: {
+          basis: {
+            type: "object",
+            properties: { type: { type: "string", const: REGISTER } },
+          },
+        },
+      },
+    },
+    {
+      if: {
+        properties: { title: { type: "string", pattern: "^urn:pdtf:unregisteredTitle:" } },
+        required: ["title"],
+      },
+      then: {
+        properties: {
+          basis: {
+            type: "object",
+            properties: { type: { type: "string", const: EPITOME } },
+          },
+        },
+      },
+    },
+  ];
+  return schema;
+};
+
 // ---------------------------------------------------------------------------
 // Main — generate all schemas and write to src/schemas/v4/
 // ---------------------------------------------------------------------------
@@ -853,6 +1032,7 @@ const generators = {
   Gift: generateGift,
   SellerCapacity: generateSellerCapacity,
   Offer: generateOffer,
+  PropertyTitleLink: generatePropertyTitleLink,
 };
 
 if (!fs.existsSync(V4_DIR)) {
@@ -1226,17 +1406,22 @@ const mapping = {
         $id: schema.$id,
         kind: DERIVED_ENTITIES.includes(name)
           ? "derived"
-          : CREDENTIAL_ENTITIES.includes(name)
+          : CREDENTIAL_ENTITIES.includes(name) ||
+            STANDING_CREDENTIAL_ENTITIES.includes(name)
           ? "credential"
           : "standalone",
-        idScheme: name === "Property" || name === "Title" ? "urn" : "did",
+        // Relationship credentials are either scoped to one Transaction (and
+        // carry `transaction`) or standing (and carry none) — D32 / D34.
+        ...(CREDENTIAL_ENTITIES.includes(name) && { scope: "transaction" }),
+        ...(STANDING_CREDENTIAL_ENTITIES.includes(name) && { scope: "standing" }),
+        idScheme: DID_ENTITIES.includes(name) ? "did" : "urn",
       },
     ])
   ),
   roundTrip: {
     entities: [...DERIVED_ENTITIES, ...CREDENTIAL_ENTITIES],
     note:
-      "All of these are required to reconstruct a V3 instance. The credentials are not redundant copies: role and every relationship live only on them, so that revoking a credential removes what it asserts rather than leaving a second copy on the transaction. Organisation is the one entity outside the round trip.",
+      "All of these are required to reconstruct a V3 instance. The credentials are not redundant copies: role and every relationship live only on them, so that revoking a credential removes what it asserts rather than leaving a second copy on the transaction. Organisation and PropertyTitleLink are outside the round trip: V3 records a participant's firm only as free text, and records no UPRN-to-title link at all, so decompose does not invent either and recompose does not need them.",
     roleImpliedByCredential: ROLE_IMPLIED_BY_CREDENTIAL,
     strippedKeySuffixes: ["Ref", "Required"],
     knownExceptions: [
@@ -1327,6 +1512,24 @@ const mapping = {
         "An offer in Transaction.offers that no participant references stays transaction data and yields no credential, since Offer requires a buyer.",
     },
   },
+  standingCredentials: {
+    PropertyTitleLink: {
+      description:
+        "A standing UPRN-to-title link. Not projected from V3. A Transaction's titlesToBeSold selects the titles being sold from the titles linked to its property; see linkedTitles() in src/utils/v4.js.",
+      issuerByTitleScheme: {
+        "urn:pdtf:titleNumber:": {
+          issuer: "HM Land Registry",
+          basis: "Register Dataset",
+        },
+        "urn:pdtf:unregisteredTitle:": {
+          issuer: "Seller's conveyancer",
+          basis: "Epitome of Title",
+        },
+      },
+      supersession:
+        "On first registration the Title for the new title number lists the unregistered URN in alsoKnownAs. An HMLR link from the same UPRN to that title supersedes the conveyancer's link to the unregistered URN; the conveyancer's link stays in force until one exists.",
+    },
+  },
   collisions: titleCollisionKeys.map((key) => ({
     key,
     entity: "Title",

package/src/utils/v4.js

@@ -826,8 +826,126 @@ const resolveV3PointerAll = (pointer) => {
 
 const resolveV3Pointer = (pointer) => resolveV3PointerAll(pointer)[0] || null;
 
+// ---------------------------------------------------------------------------
+// Standing Property–Title links (spec 01 D34)
+// ---------------------------------------------------------------------------
+const REGISTERED_TITLE = "urn:pdtf:titleNumber:";
+const UNREGISTERED_TITLE = "urn:pdtf:unregisteredTitle:";
+const REGISTER_BASIS = "Register Dataset";
+const EPITOME_BASIS = "Epitome of Title";
+
+/**
+ * Every title related to a property, and which of them a transaction sells.
+ *
+ * HMLR asserts, the seller selects: PropertyTitleLink credentials say which
+ * titles a UPRN sits on, and the Transaction's titlesToBeSold says which of
+ * those are being conveyed. Nothing else is needed to show a related title that
+ * is not being sold — a superior freehold in a leasehold flat sale, say — since
+ * it is simply a linked title the transaction does not select.
+ *
+ * Pass only links that have already been verified: signature, issuer and
+ * status (spec 14). This works on credential subjects and decides nothing about
+ * trust beyond the rule the schema also enforces, that a registered title is
+ * linked on the register and an unregistered one on the epitome.
+ *
+ * First registration: a Title whose alsoKnownAs lists an unregistered URN is
+ * the same title under its new number. Links and selections naming the old URN
+ * resolve to it, and an HMLR link from the same UPRN to the new number
+ * supersedes the conveyancer's link to the old one. Until HMLR's link exists the
+ * conveyancer's still stands, and the title is reported in `awaitingRegisterLink`.
+ *
+ * @param {object} args
+ * @param {string} args.property        Property URN (urn:pdtf:uprn:{uprn})
+ * @param {object[]} args.links         PropertyTitleLink credential subjects
+ * @param {object} [args.transaction]   Transaction, for titlesToBeSold
+ * @param {object[]} [args.titles]      Title subjects, for alsoKnownAs
+ * @returns {{
+ *   property: string,
+ *   linked: string[],          every title currently linked to the property
+ *   sold: string[],            titlesToBeSold that are linked
+ *   relatedNotSold: string[],  linked titles the transaction does not sell
+ *   unlinkedSold: string[],    titlesToBeSold with no link behind them
+ *   superseded: string[],      ids of links superseded by first registration
+ *   awaitingRegisterLink: string[], registered titles linked only on an epitome
+ * }}
+ */
+const linkedTitles = ({ property, links = [], transaction, titles = [] }) => {
+  if (!property) throw new Error("linkedTitles: property is required");
+
+  // Unregistered URN -> the registered title that now carries it.
+  const registeredAs = new Map();
+  for (const title of titles) {
+    for (const alias of title?.alsoKnownAs || []) {
+      const existing = registeredAs.get(alias);
+      if (existing && existing !== title.id) {
+        throw new Error(
+          `linkedTitles: "${alias}" is listed in alsoKnownAs by both "${existing}" and "${title.id}"`
+        );
+      }
+      registeredAs.set(alias, title.id);
+    }
+  }
+  const canonical = (urn) => registeredAs.get(urn) || urn;
+
+  const forProperty = links.filter((link) => link.property === property);
+  for (const link of forProperty) {
+    const basis = link.basis?.type;
+    const expected = link.title?.startsWith(REGISTERED_TITLE)
+      ? REGISTER_BASIS
+      : link.title?.startsWith(UNREGISTERED_TITLE)
+      ? EPITOME_BASIS
+      : null;
+    if (expected && basis !== expected) {
+      throw new Error(
+        `linkedTitles: link "${link.id || link.title}" to ${link.title} rests on "${basis}", not "${expected}"`
+      );
+    }
+  }
+
+  const fromRegister = new Set(
+    forProperty
+      .filter((link) => link.basis?.type === REGISTER_BASIS)
+      .map((link) => link.title)
+  );
+
+  const superseded = [];
+  const awaiting = new Set();
+  const linked = [];
+  const seen = new Set();
+  for (const link of forProperty) {
+    const title = canonical(link.title);
+    const isRegisteredAlias = title !== link.title;
+    if (isRegisteredAlias && fromRegister.has(title)) {
+      superseded.push(link.id || link.title);
+      continue;
+    }
+    if (isRegisteredAlias) awaiting.add(title);
+    if (!seen.has(title)) {
+      seen.add(title);
+      linked.push(title);
+    }
+  }
+
+  const selected = [
+    ...new Set((transaction?.titlesToBeSold || []).map(canonical)),
+  ];
+  const linkedSet = new Set(linked);
+  const selectedSet = new Set(selected);
+
+  return {
+    property,
+    linked,
+    sold: selected.filter((t) => linkedSet.has(t)),
+    relatedNotSold: linked.filter((t) => !selectedSet.has(t)),
+    unlinkedSold: selected.filter((t) => !linkedSet.has(t)),
+    superseded,
+    awaitingRegisterLink: linked.filter((t) => awaiting.has(t)),
+  };
+};
+
 module.exports = {
   mapping,
+  linkedTitles,
   decompose,
   recompose,
   projectRelationships,