Skip to main content
Planning application data standard

POC This is a proof of concept viewer for the planning permission specifications - your feedback will help us to improve it.

Design decision

Keep unknown answers separate from reused codelists

Decision
0024
Status
Proposed
Date
2026-10-06

Context:

The specification reuses codelists maintained elsewhere. For example, the listed-building-grade codelist refers to an external dataset of listed building grades.

An applicant may not know which value applies. We need to record that answer without adding unknown to the source dataset or maintaining a separate copy of it. An unanswered question must not be treated as an explicit answer of “I don't know”.

Decision:

Keep externally maintained codelists unchanged. Where the specification needs an explicit unknown answer, record it in a separate field.

This preserves the meaning of the source dataset and lets the specification describe uncertainty separately.

For listed building grade, require the applicant to say whether they know the grade. If they answer true, they must supply a valid grade. If they answer false, they are declaring that they do not know it and must not supply a grade. The answer is required, so omitting it is not valid.

For example, a response declaring that the grade is unknown is:

json { "listed-building-grade-known": false }

Grade known Grade Result
true Valid codelist value Valid
true Absent Invalid: grade required
false Absent Valid: applicant does not know the grade
false Present Invalid: grade is out of scope
Absent Any value Invalid: answer required

These requirements apply when the grade question is required. They do not make the module mandatory for application types that do not require it.

Conditional rules:

The module requires the known answer and requires a codelist grade only when that answer is true. When it is false, the grade field is out of scope and must not be supplied.

The co-constraint guidance uses applies-if with the boolean value true to put the grade field in scope only when the applicant says they know it. The listed-building-grade-known field itself is required in all cases.

The package exposes these constraints without evaluating submitted answers. JSON Schema generation is deferred and tracked in issue #420. Until that work is complete, generated schemas do not fully enforce this pattern.

Other answers outside a codelist:

The same principle applies when an answer does not belong in the reused source dataset: model the additional information separately in the specification.

This does not prevent adding a meaningful answer to a codelist maintained by this specification. The affected-area-type codelist includes no ("No likely impact") alongside the two affected locations. The biodiversity, geological and archaeological conservation module needs each assessment to distinguish no likely impact from an impact at either location. Because we own that codelist, adding the answer there keeps the required fields and their validation consistent without introducing separate flags. no is an explicit assessment, not an unknown answer or a missing value.

However, “other” and “unknown” are different. An unknown flag does not represent a known value missing from a codelist. If a future requirement needs an “other” answer, define how to capture that value or its description and when it is allowed. This decision does not introduce a generic reason field or allow arbitrary values in the grade field.

Interface design:

The specification defines the submitted data and the rules it must meet. Software providers decide how to present the question and capture the answer. They could show grades and “I don't know” as choices within one question, then map the answer to the appropriate field.

This follows ADR 0016: Keep form generation details separate from structured data, which is currently marked Proposed. Separate data fields do not require separate questions or controls on screen.

Consequences:

  • The source codelist remains reusable without local additions for submission-specific answers.
  • Consumers can distinguish a supplied grade, an explicitly unknown grade and an unanswered question.
  • Suppliers must apply the rule across both fields when validating submissions.
  • Each use of this pattern must define its permitted combinations and whether an answer is required.
  • This decision does not prevent adding needed answers to codelists owned by this specification, or changing those where unknown is already an intentional permitted answer, such as the pattern in ADR 0001.

Alternatives considered:

  • Add unknown to the external codelist: would mix submission uncertainty with the source dataset's actual values and depend on its maintainer accepting the change.
  • Maintain a local extended copy: would create another list to keep aligned with the source.
  • Allow an extra string through prose alone: would leave the codelist and machine-readable validation incomplete.
  • Infer unknown from a missing grade: would confuse an explicit answer with an unanswered question.
  • Use a separate unknown flag: would require the applicant to provide a flag alongside the grade or unknown answer and would add an exact-value constraint. A required known/unknown answer directly controls whether the grade applies.

Help improve this design decision

To help keep this design decision useful and up to date, you can raise feedback on GitHub.