BuildWise · Developer documentation

Professional Profile Schema

Version 1.1

This is the public contract for adding professionals to the BuildWise Professional Directory. Any tool, integration or AI model that produces a document conforming to this schema can generate BuildWise-compatible profiles with no post-processing. The same validator runs on bulk import, admin editing, AI generation and professional self-service updates, so what validates here is exactly what BuildWise accepts.

Principles

Facts are separate from opinion. Objective fields (company number, registered address, registration numbers) may carry evidence in factual_sources. Editorial fields are BuildWise’s own words and always require human sign-off before publication.
Omission beats invention. A missing field lowers a profile’s quality score. A fabricated field is a contract breach. Never send placeholders such as "unknown", "N/A" or empty strings.
Only five things are mandatory: company name, website, contact email, a location (postcode area or label) and at least one category. Everything else can arrive later; unverified facts are badged, not rejected.
Unknown fields fail the document. The schema is strict so silent data loss is impossible.
Identity is derived, not supplied. BuildWise computes the de-duplication domain and slug from the website and company name. The firm’s web domain is the de-duplication key.

Fields BuildWise owns and will reject if you send them: id, slug, website_domain, status, is_active, is_verified, is_buildwise_reviewed, is_recommended, profile_quality_score, origin, admin_notes, editorial_reviewed_by, editorial_reviewed_at, created_at, updated_at.

JSON import specification

An import is a single JSON object: a versioned envelope wrapping an array of profile objects. One file may contain up to 250 profiles.

envelope

{
  "schemaVersion": "1.1",
  "generated_at": "2026-07-31T09:00:00Z",
  "source": "ChatGPT research run 12",
  "professionals": [
    { "company_name": "...", "website": "https://...", "...": "..." }
  ]
}

Key	Meaning
schemaVersion	Required in practice. "1.1" today; a 1.x value is accepted, a 2.x value is refused.
generated_at	Optional ISO 8601 timestamp for the generation run.
source	Optional free text describing who or what produced the file.
professionals	Required array, 1–250 profile objects conforming to the field reference below.

Field reference

Rendered directly from the validator, so it can never drift from what BuildWise enforces.

fields

REQUIRED FIELDS
  company_name            string, 2-200 chars, the registered or trading name
  website                 absolute http(s) URL of the firm's own site
  contact_email           a real, published enquiries address
  postcode_area           UK outward code only, e.g. "SE22", "N4", "EC1A"
                          (may be omitted ONLY if location_label is provided)
  categories              array, 1-7 of: "architect" | "structural_engineer" | "party_wall_surveyor" | "building_control" | "builder" | "interior_designer" | "landscape_designer"

OPTIONAL FACTUAL FIELDS (omit if you cannot verify them)
  contact_name            string
  location_label          string, e.g. "East Dulwich, London"
  service_area            string, e.g. "London and the South East"
  project_types           array of: "rear_extension" | "side_return_extension" | "wrap_around_extension" | "loft_conversion" | "internal_refurbishment" | "whole_house_renovation" | "kitchen_renovation" | "bathroom_renovation" | "structural_alterations" | "other_not_sure"
  budget_bands            array of: "under_50k" | "50_150k" | "150_350k" | "350_750k" | "over_750k"
  trades                  array of small-job trades the firm carries out, from:
                          "plumbing" | "electrical" | "decorating" | "tiling" | "flooring" | "joinery" | "roofing" | "windows-doors" | "handyman" | "garden-outdoor"
                          Include a trade ONLY if the firm's own site shows it
                          does that work. This is what makes the firm eligible
                          for BuildWise small jobs.
  companies_house_number  8 digits, or 2 letters + 6 digits
  registered_address      string
  year_established        integer year between 1700 and the current year (never a future year)
  team_size               string band, e.g. "1-5", "6-20", "21-50", "50+"
  arb_number              string (architects)
  riba_number             string (architects)
  rics_number             string (surveyors)
  accreditations          array of strings, e.g. ["RIBA Chartered Practice", "FMB Member"]

OPTIONAL EDITORIAL FIELDS (your own neutral summary, not marketing copy)
  short_description       <= 500 chars, one factual sentence
  bio                     <= 5000 chars
  why_recommended         <= 1000 chars, evidence-based reasons only
  tags                    array of short strings

OPTIONAL MEDIA
  logo_url                absolute URL
  gallery_image_urls      array of absolute URLs
  featured_projects       array of objects:
                            { title, project_type, location, year,
                              description, image_urls[], is_published }

PROVENANCE
  factual_sources         object keyed by field name, values
                          { source_url, verified_at?, note? }
                          Allowed keys: company_name, website, contact_email, postcode_area, registered_address, companies_house_number, year_established, team_size, arb_number, riba_number, rics_number, accreditations
  provenance              { origin, source_urls[], ai_model?, researched_at?, note? }
                          origin is one of: "buildwise_seed" | "bulk_import" | "ai_research" | "admin_manual" | "professional_claimed"

Evidence may only be attached to these fields: company_name, website, contact_email, postcode_area, registered_address, companies_house_number, year_established, team_size, arb_number, riba_number, rics_number, accreditations.

Controlled vocabularies

Categories:

Key	Meaning
architect	Architect
structural_engineer	Structural Engineer
party_wall_surveyor	Party Wall Surveyor
building_control	Building Control
builder	Main Contractor / Builder
interior_designer	Interior Designer
landscape_designer	Landscape Designer

Project types:

Key	Meaning
rear_extension	Rear extension
side_return_extension	Side return extension
wrap_around_extension	Wrap-around extension
loft_conversion	Loft conversion
internal_refurbishment	Internal refurbishment
whole_house_renovation	Whole house renovation
kitchen_renovation	Kitchen renovation
bathroom_renovation	Bathroom renovation
structural_alterations	Structural alterations
other_not_sure	Other / not sure

Budget bands:

Key	Meaning
under_50k	Under £50k
50_150k	£50k–£150k
150_350k	£150k–£350k
350_750k	£350k–£750k
over_750k	Over £750k

ChatGPT prompt contract

Paste this verbatim, then describe the professionals you want researched. It is generated from the schema constants, so it always matches the current validator.

prompt

You are generating data for the BuildWise Professional Directory.
Target format: BuildWise Professional Profile Schema v1.1.

TASK
Research UK residential construction professionals matching the brief I give you
and return them as a single BuildWise import document.

OUTPUT RULES — these are absolute
1. Return ONLY valid JSON. No prose, no explanation, no markdown fences.
2. The top level MUST be:
   { "schemaVersion": "1.1", "generated_at": "<ISO 8601>", "source": "<short description of this run>", "professionals": [ ... ] }
3. Use exactly the field names below. Do NOT invent, rename, or nest fields.
   Unknown fields cause the whole document to be rejected.
4. Omit any field you cannot support with a real, checkable source. Never guess,
   never write "unknown", "N/A", "TBC", null placeholders, or empty strings.
5. Do NOT invent facts. Company numbers, ARB/RIBA/RICS numbers, addresses,
   founding years and team sizes must come from a source you can cite in
   factual_sources. If you cannot cite it, leave the field out.
6. Every URL must be absolute and start with http:// or https://.
7. One object per firm. Never list the same firm twice; the firm's web domain is
   the de-duplication key.
8. Editorial text (short_description, bio, why_recommended) must be neutral and
   factual. No superlatives, no sales language, no claims about price or quality
   you cannot evidence.
9. Never include fields BuildWise owns: id, slug, website_domain, status,
   is_active, is_verified, is_recommended, profile_quality_score, origin,
   admin_notes, created_at, updated_at.
10. If you are unsure whether a firm exists or is trading, exclude it entirely.

REQUIRED FIELDS
  company_name            string, 2-200 chars, the registered or trading name
  website                 absolute http(s) URL of the firm's own site
  contact_email           a real, published enquiries address
  postcode_area           UK outward code only, e.g. "SE22", "N4", "EC1A"
                          (may be omitted ONLY if location_label is provided)
  categories              array, 1-7 of: "architect" | "structural_engineer" | "party_wall_surveyor" | "building_control" | "builder" | "interior_designer" | "landscape_designer"

OPTIONAL FACTUAL FIELDS (omit if you cannot verify them)
  contact_name            string
  location_label          string, e.g. "East Dulwich, London"
  service_area            string, e.g. "London and the South East"
  project_types           array of: "rear_extension" | "side_return_extension" | "wrap_around_extension" | "loft_conversion" | "internal_refurbishment" | "whole_house_renovation" | "kitchen_renovation" | "bathroom_renovation" | "structural_alterations" | "other_not_sure"
  budget_bands            array of: "under_50k" | "50_150k" | "150_350k" | "350_750k" | "over_750k"
  trades                  array of small-job trades the firm carries out, from:
                          "plumbing" | "electrical" | "decorating" | "tiling" | "flooring" | "joinery" | "roofing" | "windows-doors" | "handyman" | "garden-outdoor"
                          Include a trade ONLY if the firm's own site shows it
                          does that work. This is what makes the firm eligible
                          for BuildWise small jobs.
  companies_house_number  8 digits, or 2 letters + 6 digits
  registered_address      string
  year_established        integer year between 1700 and the current year (never a future year)
  team_size               string band, e.g. "1-5", "6-20", "21-50", "50+"
  arb_number              string (architects)
  riba_number             string (architects)
  rics_number             string (surveyors)
  accreditations          array of strings, e.g. ["RIBA Chartered Practice", "FMB Member"]

OPTIONAL EDITORIAL FIELDS (your own neutral summary, not marketing copy)
  short_description       <= 500 chars, one factual sentence
  bio                     <= 5000 chars
  why_recommended         <= 1000 chars, evidence-based reasons only
  tags                    array of short strings

OPTIONAL MEDIA
  logo_url                absolute URL
  gallery_image_urls      array of absolute URLs
  featured_projects       array of objects:
                            { title, project_type, location, year,
                              description, image_urls[], is_published }

PROVENANCE
  factual_sources         object keyed by field name, values
                          { source_url, verified_at?, note? }
                          Allowed keys: company_name, website, contact_email, postcode_area, registered_address, companies_house_number, year_established, team_size, arb_number, riba_number, rics_number, accreditations
  provenance              { origin, source_urls[], ai_model?, researched_at?, note? }
                          origin is one of: "buildwise_seed" | "bulk_import" | "ai_research" | "admin_manual" | "professional_claimed"

A MINIMAL, VALID PROFILE LOOKS LIKE THIS
{
  "company_name": "Kelso Structural Design",
  "website": "https://kelsostructural.com",
  "contact_email": "mail@kelsostructural.com",
  "postcode_area": "BS8",
  "categories": [
    "structural_engineer"
  ],
  "project_types": [
    "structural_alterations",
    "rear_extension"
  ],
  "budget_bands": [],
  "short_description": "Structural engineering for domestic extensions, removals and loft conversions.",
  "factual_sources": {},
  "provenance": {
    "origin": "ai_research",
    "source_urls": [
      "https://kelsostructural.com"
    ]
  }
}

BEFORE YOU ANSWER
- Re-read every object and delete any field you cannot source.
- Confirm the JSON parses and that "schemaVersion" is "1.1".
- Return the JSON document and nothing else.

Small-job trade sourcing

Trade companies for single-trade work use the same document format. Declare coverage with the optional trades array.

trade-prompt

You are sourcing trade companies for BuildWise small jobs
(single-trade work: swapping a bathroom sink, a rewire, a roof repair, a room repaint).
Target format: BuildWise Professional Profile Schema v1.1.

TASK
For each trade and postcode area I give you, research established UK companies that
actually carry out that trade, and return them as ONE BuildWise import document.

TRADE VOCABULARY — use these slugs verbatim in "trades"
  plumbing              Plumbing & heating
  electrical            Electrical
  decorating            Painting, decorating & plastering
  tiling                Tiling
  flooring              Flooring
  joinery               Carpentry & joinery
  roofing               Roofing & guttering
  windows-doors         Windows & doors
  handyman              Handyperson & repairs
  garden-outdoor        Garden & outdoor

RULES SPECIFIC TO TRADE SOURCING
1. "categories" is still required. Use ["builder"] unless the firm is genuinely one of
   the professional categories (architect, structural_engineer, ...).
2. "trades" must list every small-job trade the firm evidently covers, and nothing more.
   A firm with no evidenced trade must be excluded from a trade sourcing run.
3. Prefer firms with a real website, a published enquiries email and a stated coverage
   area. A firm with no contactable email is imported as a draft and cannot go live.
4. Set "postcode_area" to the firm's own base, and "service_area" to the areas it covers.
5. In "provenance", set origin to "ai_research" and list the pages you used.

REQUIRED FIELDS
  company_name            string, 2-200 chars, the registered or trading name
  website                 absolute http(s) URL of the firm's own site
  contact_email           a real, published enquiries address
  postcode_area           UK outward code only, e.g. "SE22", "N4", "EC1A"
                          (may be omitted ONLY if location_label is provided)
  categories              array, 1-7 of: "architect" | "structural_engineer" | "party_wall_surveyor" | "building_control" | "builder" | "interior_designer" | "landscape_designer"

OPTIONAL FACTUAL FIELDS (omit if you cannot verify them)
  contact_name            string
  location_label          string, e.g. "East Dulwich, London"
  service_area            string, e.g. "London and the South East"
  project_types           array of: "rear_extension" | "side_return_extension" | "wrap_around_extension" | "loft_conversion" | "internal_refurbishment" | "whole_house_renovation" | "kitchen_renovation" | "bathroom_renovation" | "structural_alterations" | "other_not_sure"
  budget_bands            array of: "under_50k" | "50_150k" | "150_350k" | "350_750k" | "over_750k"
  trades                  array of small-job trades the firm carries out, from:
                          "plumbing" | "electrical" | "decorating" | "tiling" | "flooring" | "joinery" | "roofing" | "windows-doors" | "handyman" | "garden-outdoor"
                          Include a trade ONLY if the firm's own site shows it
                          does that work. This is what makes the firm eligible
                          for BuildWise small jobs.
  companies_house_number  8 digits, or 2 letters + 6 digits
  registered_address      string
  year_established        integer year between 1700 and the current year (never a future year)
  team_size               string band, e.g. "1-5", "6-20", "21-50", "50+"
  arb_number              string (architects)
  riba_number             string (architects)
  rics_number             string (surveyors)
  accreditations          array of strings, e.g. ["RIBA Chartered Practice", "FMB Member"]

OPTIONAL EDITORIAL FIELDS (your own neutral summary, not marketing copy)
  short_description       <= 500 chars, one factual sentence
  bio                     <= 5000 chars
  why_recommended         <= 1000 chars, evidence-based reasons only
  tags                    array of short strings

OPTIONAL MEDIA
  logo_url                absolute URL
  gallery_image_urls      array of absolute URLs
  featured_projects       array of objects:
                            { title, project_type, location, year,
                              description, image_urls[], is_published }

PROVENANCE
  factual_sources         object keyed by field name, values
                          { source_url, verified_at?, note? }
                          Allowed keys: company_name, website, contact_email, postcode_area, registered_address, companies_house_number, year_established, team_size, arb_number, riba_number, rics_number, accreditations
  provenance              { origin, source_urls[], ai_model?, researched_at?, note? }
                          origin is one of: "buildwise_seed" | "bulk_import" | "ai_research" | "admin_manual" | "professional_claimed"

BEFORE YOU ANSWER
- Delete any firm whose trade coverage you could not see on its own site.
- Confirm the JSON parses and that "schemaVersion" is "1.1".
- Return the JSON document and nothing else.

Reference examples

Three reference implementations, each validated in the BuildWise test suite: a rich, fully sourced architect; a mid-completeness main contractor; and a minimum-viable structural engineer. Firms shown are illustrative placeholders.

architect

{
  "company_name": "Fielder & Rowe Architects",
  "website": "https://www.fielderrowe.co.uk",
  "contact_email": "studio@fielderrowe.co.uk",
  "contact_name": "Anna Rowe",
  "postcode_area": "SE22",
  "location_label": "East Dulwich, London",
  "service_area": "London and the South East",
  "categories": [
    "architect"
  ],
  "project_types": [
    "rear_extension",
    "side_return_extension",
    "loft_conversion",
    "whole_house_renovation"
  ],
  "budget_bands": [
    "150_350k",
    "350_750k"
  ],
  "companies_house_number": "09123456",
  "registered_address": "42 Lordship Lane, London SE22 8HJ",
  "year_established": 2011,
  "team_size": "6-20",
  "arb_number": "078451",
  "riba_number": "1874523",
  "accreditations": [
    "RIBA Chartered Practice",
    "ARB Registered"
  ],
  "short_description": "Residential practice specialising in rear and side-return extensions to Victorian terraces, with in-house planning support.",
  "bio": "Fielder & Rowe is a six-person studio working almost exclusively on London period housing. The practice runs projects from feasibility through planning, building regulations and contract administration, and typically works on rear extensions, side returns and full-house refurbishments in the £150k–£750k range.",
  "why_recommended": "Deep experience of conservation-area extensions in south London, and a track record of taking projects through to site with the same team that designed them.",
  "tags": [
    "conservation area",
    "period property",
    "planning-led"
  ],
  "logo_url": "https://www.fielderrowe.co.uk/assets/logo.png",
  "gallery_image_urls": [
    "https://www.fielderrowe.co.uk/assets/dulwich-01.jpg"
  ],
  "featured_projects": [
    {
      "title": "Dulwich rear extension and kitchen",
      "project_type": "rear_extension",
      "location": "East Dulwich, London",
      "year": 2024,
      "description": "Single-storey rear extension with a structural glass corner, opening a Victorian terrace into the garden. Delivered under a JCT Minor Works contract.",
      "image_urls": [
        "https://www.fielderrowe.co.uk/assets/dulwich-01.jpg"
      ],
      "is_published": true
    }
  ],
  "factual_sources": {
    "company_name": {
      "source_url": "https://find-and-update.company-information.service.gov.uk/company/09123456",
      "verified_at": "2026-07-30T10:00:00Z"
    },
    "companies_house_number": {
      "source_url": "https://find-and-update.company-information.service.gov.uk/company/09123456",
      "verified_at": "2026-07-30T10:00:00Z"
    },
    "registered_address": {
      "source_url": "https://find-and-update.company-information.service.gov.uk/company/09123456"
    },
    "arb_number": {
      "source_url": "https://architects-register.org.uk/",
      "note": "Checked against the ARB register"
    },
    "year_established": {
      "source_url": "https://www.fielderrowe.co.uk/about"
    }
  },
  "provenance": {
    "origin": "ai_research",
    "source_urls": [
      "https://www.fielderrowe.co.uk/about",
      "https://www.architecture.com/find-an-architect"
    ],
    "ai_model": "gpt-research-run-12",
    "researched_at": "2026-07-30T09:40:00Z"
  }
}

builder

{
  "company_name": "Northgate Construction Ltd",
  "website": "https://northgateconstruction.co.uk",
  "contact_email": "enquiries@northgateconstruction.co.uk",
  "contact_name": "Dave Whitcombe",
  "postcode_area": "N4",
  "location_label": "Finsbury Park, London",
  "service_area": "North and east London, within the M25",
  "categories": [
    "builder"
  ],
  "project_types": [
    "rear_extension",
    "loft_conversion",
    "internal_refurbishment",
    "structural_alterations"
  ],
  "budget_bands": [
    "50_150k",
    "150_350k",
    "350_750k"
  ],
  "companies_house_number": "07654321",
  "year_established": 2008,
  "team_size": "21-50",
  "accreditations": [
    "FMB Member",
    "TrustMark Registered"
  ],
  "short_description": "Main contractor delivering extensions, loft conversions and structural alterations across north London.",
  "why_recommended": "Directly employed carpentry and groundworks teams, which keeps programme risk down on structural work in occupied houses.",
  "tags": [
    "occupied works",
    "structural alterations"
  ],
  "featured_projects": [
    {
      "title": "Highbury loft conversion and rear infill",
      "project_type": "loft_conversion",
      "location": "Highbury, London",
      "year": 2025,
      "description": "Combined loft conversion and rear infill to a four-storey terrace, completed in 22 weeks with the family in occupation.",
      "image_urls": [],
      "is_published": true
    }
  ],
  "factual_sources": {
    "companies_house_number": {
      "source_url": "https://find-and-update.company-information.service.gov.uk/company/07654321",
      "verified_at": "2026-07-30T11:15:00Z"
    },
    "accreditations": {
      "source_url": "https://www.fmb.org.uk/find-a-builder/"
    }
  },
  "provenance": {
    "origin": "bulk_import",
    "source_urls": [
      "https://northgateconstruction.co.uk/about"
    ],
    "researched_at": "2026-07-30T11:00:00Z"
  }
}

structural engineer

{
  "company_name": "Kelso Structural Design",
  "website": "https://kelsostructural.com",
  "contact_email": "mail@kelsostructural.com",
  "postcode_area": "BS8",
  "categories": [
    "structural_engineer"
  ],
  "project_types": [
    "structural_alterations",
    "rear_extension"
  ],
  "budget_bands": [],
  "short_description": "Structural engineering for domestic extensions, removals and loft conversions.",
  "factual_sources": {},
  "provenance": {
    "origin": "ai_research",
    "source_urls": [
      "https://kelsostructural.com"
    ]
  }
}

The complete document, ready to import:

import document

{
  "schemaVersion": "1.1",
  "generated_at": "2026-07-31T09:00:00Z",
  "source": "Reference example — BuildWise documentation",
  "professionals": [
    {
      "company_name": "Fielder & Rowe Architects",
      "website": "https://www.fielderrowe.co.uk",
      "contact_email": "studio@fielderrowe.co.uk",
      "contact_name": "Anna Rowe",
      "postcode_area": "SE22",
      "location_label": "East Dulwich, London",
      "service_area": "London and the South East",
      "categories": [
        "architect"
      ],
      "project_types": [
        "rear_extension",
        "side_return_extension",
        "loft_conversion",
        "whole_house_renovation"
      ],
      "budget_bands": [
        "150_350k",
        "350_750k"
      ],
      "companies_house_number": "09123456",
      "registered_address": "42 Lordship Lane, London SE22 8HJ",
      "year_established": 2011,
      "team_size": "6-20",
      "arb_number": "078451",
      "riba_number": "1874523",
      "accreditations": [
        "RIBA Chartered Practice",
        "ARB Registered"
      ],
      "short_description": "Residential practice specialising in rear and side-return extensions to Victorian terraces, with in-house planning support.",
      "bio": "Fielder & Rowe is a six-person studio working almost exclusively on London period housing. The practice runs projects from feasibility through planning, building regulations and contract administration, and typically works on rear extensions, side returns and full-house refurbishments in the £150k–£750k range.",
      "why_recommended": "Deep experience of conservation-area extensions in south London, and a track record of taking projects through to site with the same team that designed them.",
      "tags": [
        "conservation area",
        "period property",
        "planning-led"
      ],
      "logo_url": "https://www.fielderrowe.co.uk/assets/logo.png",
      "gallery_image_urls": [
        "https://www.fielderrowe.co.uk/assets/dulwich-01.jpg"
      ],
      "featured_projects": [
        {
          "title": "Dulwich rear extension and kitchen",
          "project_type": "rear_extension",
          "location": "East Dulwich, London",
          "year": 2024,
          "description": "Single-storey rear extension with a structural glass corner, opening a Victorian terrace into the garden. Delivered under a JCT Minor Works contract.",
          "image_urls": [
            "https://www.fielderrowe.co.uk/assets/dulwich-01.jpg"
          ],
          "is_published": true
        }
      ],
      "factual_sources": {
        "company_name": {
          "source_url": "https://find-and-update.company-information.service.gov.uk/company/09123456",
          "verified_at": "2026-07-30T10:00:00Z"
        },
        "companies_house_number": {
          "source_url": "https://find-and-update.company-information.service.gov.uk/company/09123456",
          "verified_at": "2026-07-30T10:00:00Z"
        },
        "registered_address": {
          "source_url": "https://find-and-update.company-information.service.gov.uk/company/09123456"
        },
        "arb_number": {
          "source_url": "https://architects-register.org.uk/",
          "note": "Checked against the ARB register"
        },
        "year_established": {
          "source_url": "https://www.fielderrowe.co.uk/about"
        }
      },
      "provenance": {
        "origin": "ai_research",
        "source_urls": [
          "https://www.fielderrowe.co.uk/about",
          "https://www.architecture.com/find-an-architect"
        ],
        "ai_model": "gpt-research-run-12",
        "researched_at": "2026-07-30T09:40:00Z"
      }
    },
    {
      "company_name": "Northgate Construction Ltd",
      "website": "https://northgateconstruction.co.uk",
      "contact_email": "enquiries@northgateconstruction.co.uk",
      "contact_name": "Dave Whitcombe",
      "postcode_area": "N4",
      "location_label": "Finsbury Park, London",
      "service_area": "North and east London, within the M25",
      "categories": [
        "builder"
      ],
      "project_types": [
        "rear_extension",
        "loft_conversion",
        "internal_refurbishment",
        "structural_alterations"
      ],
      "budget_bands": [
        "50_150k",
        "150_350k",
        "350_750k"
      ],
      "companies_house_number": "07654321",
      "year_established": 2008,
      "team_size": "21-50",
      "accreditations": [
        "FMB Member",
        "TrustMark Registered"
      ],
      "short_description": "Main contractor delivering extensions, loft conversions and structural alterations across north London.",
      "why_recommended": "Directly employed carpentry and groundworks teams, which keeps programme risk down on structural work in occupied houses.",
      "tags": [
        "occupied works",
        "structural alterations"
      ],
      "featured_projects": [
        {
          "title": "Highbury loft conversion and rear infill",
          "project_type": "loft_conversion",
          "location": "Highbury, London",
          "year": 2025,
          "description": "Combined loft conversion and rear infill to a four-storey terrace, completed in 22 weeks with the family in occupation.",
          "image_urls": [],
          "is_published": true
        }
      ],
      "factual_sources": {
        "companies_house_number": {
          "source_url": "https://find-and-update.company-information.service.gov.uk/company/07654321",
          "verified_at": "2026-07-30T11:15:00Z"
        },
        "accreditations": {
          "source_url": "https://www.fmb.org.uk/find-a-builder/"
        }
      },
      "provenance": {
        "origin": "bulk_import",
        "source_urls": [
          "https://northgateconstruction.co.uk/about"
        ],
        "researched_at": "2026-07-30T11:00:00Z"
      }
    },
    {
      "company_name": "Kelso Structural Design",
      "website": "https://kelsostructural.com",
      "contact_email": "mail@kelsostructural.com",
      "postcode_area": "BS8",
      "categories": [
        "structural_engineer"
      ],
      "project_types": [
        "structural_alterations",
        "rear_extension"
      ],
      "budget_bands": [],
      "short_description": "Structural engineering for domestic extensions, removals and loft conversions.",
      "factual_sources": {},
      "provenance": {
        "origin": "ai_research",
        "source_urls": [
          "https://kelsostructural.com"
        ]
      }
    }
  ]
}

Validation report

Validation never answers just “invalid”. Every document returns a field-level report: how much is populated, what is missing, what is unverified, and what looks suspicious. Blocking problems are errors; everything else is advisory.

report

BuildWise Professional Directory — validation report (schema 1.1)

✓ 1 of 1 profiles importable

————————————————————————————————————————————————
✓ Kelso Structural Design

✓ 8 of 25 fields populated (quality score ≈ 44/100)

⚠ Missing:
  - Contact name
  - Companies House number
  - Registered address
  - Year established
  - Team size
  - ARB number
  - RIBA number
  - RICS number
  - Accreditations
  - Service area
  - Budget bands
  - Bio
  - Why recommended
  - Tags
  - Logo
  - Featured projects
  - Gallery images

⚠ Unverified (no source URL):
  - Company name
  - Website
  - Contact email
  - Location

Warnings:
  - no Companies House number — de-duplication will rely on the web domain alone
  - no accreditations for a structural engineer (expected IStructE / ICE)
  - no factual_sources supplied — every fact will publish as unverified
  - no logo — cards fall back to initials

Endpoints

Both endpoints are public, read-only and CORS-enabled.

shell

# Fetch the machine-readable contract, vocabularies, prompt and examples
curl https://buildwise-plan.co.uk/api/public/professional-schema/v1

# Validate a document without importing it
curl -X POST https://buildwise-plan.co.uk/api/public/professional-schema/validate \
  -H "Content-Type: application/json" \
  --data-binary @professionals.json

The validate endpoint stores nothing and returns both a structured report and a rendered report_text. Importing into the live directory remains an authenticated admin action.

Versioning and evolution

Versions move 1.0 → 1.1 → 1.2 → 2.0. The policy is fixed:

Minor releases are additive or relaxing only. New optional fields, new enum members, looser limits. Any valid 1.0 document stays valid under every 1.x — old generator prompts keep working untouched.
Major releases may change required fields or semantics. 1.x documents are not silently upgraded: they pass through a declared migration that records the original payload in the import audit trail.
Deprecation takes at least one minor cycle. A field is marked deprecated in a minor release, keeps working, and is only removed at the next major.
Unrecognised versions fail loudly. A newer minor is accepted with a warning listing the fields ignored; a different major is refused with an explicit message rather than partially imported.

v1.0superseded · 2026-07-31 · additive

First public release of the Professional Profile Schema.
Mandatory set: company_name, website, contact_email, one of postcode_area/location_label, at least one category.
All other factual fields are optional and may be published unverified; they lower the profile quality score instead of blocking import.

v1.1current · 2026-08-11 · additive

Adds the optional `trades` array, registering a company for BuildWise small-job trades (bathroom sink swaps, rewires, roof repairs and the like).
Trades are stored as `trade:<slug>` tags and are the only evidence that promotes a company to "Registered for this trade" in small-job suggestions.
Any 1.0 document remains valid without modification.