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.

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)

Modular sub-pieces of NTS2 — opt into them individually on top of an NTS 2023 base. Each adds one specific feature so adopters can stage their migration from NTS → NTS2 without committing to the entire 2025 spec at once.

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:

Bounded-context map

Each overlay belongs to exactly one bounded context:

The extension overlays (jk, tf, …) are all sub-pieces of NTS2, so they belong to Estate Agency.

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)