PDTF overlays

An overlay is a JSON-Schema artefact that adds one form, search or document to the base PDTF transaction schema. Overlays are the unit of composition the schema package ships in — pick the ones your use case needs, merge them on top of the base, and you get a complete validating schema.

The overlay landscape

One base schema; five business contexts that own overlays; a sixth (Property Tech) that runs on the base alone; and 16 extension overlays that sit inside Estate Agency as NTS2 fragments.

The four columns in the diagram below, left to right:

1. Base schema — the single pdtf-transaction.json that every overlay layers onto.
2. Bounded contexts — the six business domains in the DDD model (Estate Agency, Conveyancing, Mortgage Lending, Surveying, Property Tech, Property Data Services). Every overlay belongs to exactly one.
3. Main overlays — one JSON Schema per form, search or document (BASPI, TA6, CON29R, …). 18 in total, distributed across five of the six contexts.
4. Extension overlays — 16 modular sub-pieces of NTS2, all inside Estate Agency. Adopt them individually to migrate from NTS 2023 → NTS2 2025 one topic at a time.

What an overlay is — and is not

An overlay is a draft-07 JSON Schema that mirrors the shape of the base transaction but only specifies what it adds or constrains. The merge function turns the base + overlays into a complete schema.

Overlays predate the DDD analysis — the bounded-context model is a retrofit onto a partition that was already there. So the answer to "are overlays the same as bounded contexts?" is: no, but they map cleanly onto them.

The catalogue

Main overlays (18)

Bounded context is the business domain the overlay belongs to (one of six). Status is the lifecycle state of the overlay file: active means current, superseded / legacy means a newer overlay covers the same form but the older one is still shipped in v3 for backward compatibility. The two are orthogonal — every legacy overlay still belongs to its original bounded context.

Property information forms

What the seller declares about the property.

Legal forms (Law Society)

What the conveyancer asks for.

Search and survey forms

What the third-party data providers return.

Specialist

Newer overlays covering domain-specific data.

Extension overlays (16)

The 18 main overlays above span five bounded contexts. The 16 extension overlays here all belong to one — Estate Agency — because they fragment nts2 (the 2025 Material Information spec that estate agents publish when listing a property) into opt-in pieces.

Each extension adds a single topic to an nts 2023 base, so an estate agent or listing platform can adopt NTS2 changes one topic at a time instead of switching their whole pipeline to the 2025 spec in one go.

Four entries below have — in the NTS2 ref column. Those cover topics that sit alongside NTS2 (general property data) rather than mapping to a specific NTS2 section.

Specialist issues

Property features

Ownership & financial

Utilities & services

Transaction

Bounded-context map

Inverse view of the catalogue — each overlay belongs to exactly one bounded context. The 16 extension overlays all sit inside Estate Agency (as NTS2 fragments) and aren't repeated here.

How an overlay is defined

Every overlay is a draft-07 JSON Schema with this skeletal shape:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://trust.propdata.org.uk/schemas/v3/overlays/baspi5.json",
  "required": ["participants", "propertyPack"],
  "properties": {
    "propertyPack": {
      "baspi5Ref": "B",
      "required": ["priceInformation", "ownership", "..."],
      "properties": {
        "priceInformation": {
          "baspi5Ref": "B.1",
          "properties": { /* … */ }
        }
      }
    }
  }
}

The pieces that make an overlay an overlay:

• Form reference attributes — baspi5Ref, ntsRef, nts2Ref, ta6Ref, ta7Ref, ta10Ref, lpe1Ref, fme1Ref, con29RRef, con29DWRef, rdsRef, piqRef. Each schema node carries the paper-form section number it traces back to.
• required arrays — fields the form mandates. Different overlays make different things required.
• title / description annotations — form-specific wording (often different from the base or another overlay).
• oneOf discriminators — the canonical pattern is the yesNo discriminator: when yesNo = "Yes", a details field becomes required.

How overlays are used at runtime

Composition happens via the library entrypoint getTransactionSchema(schemaId, overlays[]) in index.js:

const { getTransactionSchema } = require('@pdtf/schemas');

// Estate-agency product:
const eaSchema = getTransactionSchema(
  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
  ["baspi5", "nts2"]
);

// Conveyancer product:
const cnvSchema = getTransactionSchema(
  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
  ["ta6", "ta7", "ta10", "lpe1"]
);

// Selective NTS → NTS2 migration:
const stagedSchema = getTransactionSchema(
  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
  ["nts2023", "jk", "tf"]  // NTS 2023 + Japanese knotweed + transfer fees
);

Under the hood, the merge pipeline is:

Names and aliases

Overlays are registered in overlaysMap[schemaId] in index.js under versioned aliases as well as the plain filename stem. Both work:

Where this lives

• Overlay JSON files: source/03-standards/schemas/src/schemas/v3/overlays/
• Extension overlays: source/03-standards/schemas/src/schemas/v3/overlays/extensions/
• Upstream README: source/03-standards/schemas/src/schemas/v3/overlays/README.md
• Merge entrypoint: source/03-standards/schemas/index.js (function getTransactionSchema at line 170)
• Bounded-context mapping rationale: Bounded contexts (DDD)