pedwfrontend/docs/query-profile-compatibility.md

Query Profile Compatibility Contract

Purpose

This document records the current compatibility contract around:

• actions/selectQueryTypes.js

That file is primarily:

• CRM/OData query-shape configuration
• CRM compatibility handling

It is not primarily business-rule logic.

Its main job today is to ensure the portal requests the fields that each CRM entity actually exposes so downstream case-summary, representation, status, lifecycle, and infrastructure views continue to function.

---

Source of Truth

The CRM field names are the source of truth.

The website must query the fields that actually exist on each CRM entity.

This includes preserving:

• historic naming differences
• spelling mistakes
• singular/plural variants
• entity-specific field names
• legislation-specific field models

Future work must treat field selection as a compatibility-sensitive integration concern first.

The goal is not to make the query profiles look tidy.

The goal is to preserve the fields that the live system currently depends on.

---

Appeal-Type Differences

Different appeal types legitimately require different fields because they support different:

• legislation
• workflows
• representation windows
• event models
• authority models
• infrastructure/project processes

This means:

• similar-looking appeal types must not automatically be treated as identical
• near-duplicate field bundles must not automatically be collapsed
• infrastructure-style entities must not automatically be forced into planning-style shapes
• minimal profiles must not automatically be expanded to match richer bundles

Bundle-by-bundle evaluation is required.

---

CRM Compatibility Variants

The current compatibility contract includes representative field variants that must be preserved.

Specialist-process variants

• pinswg_specialistcaseprocess
• pinswg_speacialistcaseprocess

These are not interchangeable in the current query profiles.

Representative characterization showed:

• ROW uses pinswg_specialistcaseprocess
• Adverts uses pinswg_speacialistcaseprocess

Start-date variants

• pinswg_startdate
• pinswg_startdates
• pinswg_applicationacceptedasvalid

These reflect different representation-window and process models across entities.

Statement-date variants

• pinswg_statementduedate
• pinswg_statementsduedate

These must not be normalized away.

Project description variants

• pinswg_projectdescription
• pinswg_projectdiscription

Harbour Revision Orders currently preserve the misspelled variant.

Decision variant

• pinswg_dicision

Planning S78 currently preserves this field name in its query profile.

Other representative compatibility-sensitive variants

• pinswg_otherpartiesstatement

• pinswg_otherpartiesstatements

• pinswg_otherpartiesstmt

• pinswg_suspensionstartdates

• pinswg_suspensionstartdate

• pinswg_startdateofevent

• pinswg_startdateoftheevent

• pinswg_starttimeofevent

• pinswg_starttimeoftheevent

• pinswg_startdatetimeiftheevent

These variants must be preserved until characterization-based extraction or change work explicitly proves otherwise.

---

Characterized Field Families

The current characterization work identifies the following conceptual families already present inside selectQueryTypes.js.

1. Planning-style fields

Representative concerns include:

• base case identity fields
• planning-style address fields
• decision/date/status fields
• event support fields

These appear across many planning and enforcement-style entities, but not always with identical field names.

2. Representation-window fields

Representative fields include:

• pinswg_startdate
• pinswg_startdates
• pinswg_applicationacceptedasvalid
• pinswg_statementduedate
• pinswg_statementsduedate
• pinswg_finalcommentsduedate
• pinswg_endofrepresentationperiod

These coexist today and reflect different entity models.

3. Specialist-process fields

Representative fields include:

• pinswg_specialistcaseprocess
• pinswg_speacialistcaseprocess

These must not be silently unified.

4. Infrastructure / project fields

Representative concerns include:

• project description
• project location
• submission / publication milestones
• recommendation / report fields
• suspension dates
• grid-reference fields

These are particularly important in DNS / Harbour / Transport / Electricity style bundles.

5. Authority / LPA fields

Representative fields include:

• _pinswg_localplanningauthority_value
• _pinswg_associatedlpa_value
• pinswg_relevantauthorityname

These represent different authority models across bundles.

6. Consultation fields

Representative fields include:

• pinswg_consultationopen
• pinswg_consultationclose

These are currently characteristic of SIPS-style profiles.

7. Minimal-profile bundles

Representative examples include:

• pinswg_nonvalidations
• pinswg_ldps

These are intentionally smaller than richer planning and infrastructure bundles.

---

Characterized Divergences

Characterization work also confirmed that some similar bundles intentionally differ.

Representative examples:

Advert vs ROW specialist-process fields

• Advert preserves pinswg_speacialistcaseprocess
• ROW preserves pinswg_specialistcaseprocess

These must not be accidentally collapsed into one shared field choice.

Harbour vs DNS project-description fields

• Harbour preserves pinswg_projectdiscription
• DNS preserves pinswg_projectdescription

Suspension-start variants

• DNS preserves pinswg_suspensionstartdates
• Harbour and Transport preserve pinswg_suspensionstartdate

Authority / LPA model differences

• S78 preserves _pinswg_localplanningauthority_value
• ROW preserves _pinswg_associatedlpa_value plus pinswg_relevantauthorityname
• DNS preserves _pinswg_associatedlpa_value without the planning-style relevant-authority field

Event-date and event-time variants

Representative coexistence includes:

• pinswg_startdateofevent
• pinswg_startdateoftheevent
• pinswg_starttimeofevent
• pinswg_starttimeoftheevent
• pinswg_startdatetimeiftheevent

Representation-support differences in similar bundles

Representative differences include:

• singular vs plural other-parties fields
• singular vs plural statement-due-date fields
• bundle-specific combinations of proof/questionnaire/final-comments fields

These differences must be treated as compatibility-sensitive unless explicitly re-characterized.

---

Future Guidance

Future work in this area should follow these rules:

1. Characterize first

   • prove current behaviour before changing structure

2. Extract later

   • do not extract shared bundles or constants until the current compatibility contract is protected

3. Preserve compatibility

   • CRM field variants are not “cleanup noise”; they are part of the current live contract

4. Evaluate bundle-by-bundle

   • each bundle should be assessed on its own actual field requirements

5. Avoid broad normalization

   • do not assume similar names mean safe consolidation

6. Protect intentional differences

   • especially for:
     • specialist-process fields
     • representation-window fields
     • project-description fields
     • suspension-start fields
     • authority/LPA fields
     • event-date/time fields

The safest sequence remains:

• characterize current bundles
• characterize current families
• characterize duplicated clusters and divergences
• only then consider bounded extraction work

---

Explicit Non-Goals

This characterization and documentation work does not:

• rename CRM fields
• remove typo fields
• redesign CRM entities
• standardize legislation-specific data
• force appeal types into identical query profiles
• introduce a query DSL
• move this concern into a broader business-rule domain boundary

Any future cleanup or extraction must preserve the documented compatibility contract unless an explicit behaviour-change decision is made.