[WHIT-2788] Configurable document types documentation update#10990
Conversation
eYinka
changed the title
ryanb-gds
left a comment
ryanb-gds
left a comment
There was a problem hiding this comment.
This is great, really thorough and easy to follow.
I do wonder if the wording around removing nested attribute structures is a little strong, as it suggests we've made an active choice to remove them rather than a passive choice to not implement them in the new schema until we have a clear need. But that might just be because I'm a little unclear in my own end what the vision is for those now.
| We refactored the configurable document type schema to separate concerns: | ||
|
|
||
| 1. Introduced a top-level `forms` hash describing UI forms and their fields (label, description, block type), replacing `settings.edit_screens`. | ||
| 2. Replaced `schema.properties` with `schema.attributes`, limited to leaf attributes; we no longer model nested properties at the schema level. |
There was a problem hiding this comment.
We aren't really limiting attributes to "leaf attributes" - we just don't currently have a need for more complex attribute shapes. But I wouldn't rule out reintroducing them in future, and in fact we are introducing arrays in the work on social media accounts.
There was a problem hiding this comment.
I agree, although the intention was not to totally rule it out forever. Just based it on the current implementation. Will re-word to make it clearer.
| 1. Introduced a top-level `forms` hash describing UI forms and their fields (label, description, block type), replacing `settings.edit_screens`. | ||
| 2. Replaced `schema.properties` with `schema.attributes`, limited to leaf attributes; we no longer model nested properties at the schema level. | ||
| 3. Introduced a top-level `presenters` hash to describe how attribute values are mapped or transformed for downstream consumers (e.g. Publishing API), helping to decouple UI layout from payload shape. | ||
| 4. Flattened validation definitions so `schema.validations` lists validators by attribute name; nested validations inside a property definition are removed. |
There was a problem hiding this comment.
Again, I don't think we have done away with nested validations, we're just not using them currently
| 2. Replaced `schema.properties` with `schema.attributes`, limited to leaf attributes; we no longer model nested properties at the schema level. | ||
| 3. Introduced a top-level `presenters` hash to describe how attribute values are mapped or transformed for downstream consumers (e.g. Publishing API), helping to decouple UI layout from payload shape. | ||
| 4. Flattened validation definitions so `schema.validations` lists validators by attribute name; nested validations inside a property definition are removed. | ||
| 5. Removed the option to declare attributes as `object` types to enforce the flattened model and prevent reintroduction of nested schema structures. |
There was a problem hiding this comment.
You can still use object types and it will work, you'll just get Rails' default hash implementation rather than a nested block content object. I expect nested block content objects may reappear at some point.
| - All configurable document type definitions must use `schema.attributes`, `forms`, and `presenters`; `settings.edit_screens` and nested property validations are no longer supported. | ||
| - UI layout changes (field grouping, titles, descriptions, block types) can now be made in `forms` without impacting Publishing API payloads, which are defined in `presenters`. | ||
| - Validators will run against the flattened `schema.attributes` namespace. Added tests ensure nested data values stored in block content are preserved when present in the payload. | ||
| - Future support for genuinely nested attribute schemas or arrays would need a new design rather than reintroducing `object` types. |
There was a problem hiding this comment.
Ah, I see what you mean above now when you say we're not supporting objects any longer. Yeah, I'd agree that they will probably work slightly differently as and when we need to reintroduce them.
This commit adds an ADR that explains why we have adopted the new forms structure in configurable documents schema and the benefit for us, especially with validating nested blocks. PR: #10972
As we have refactored configurable document types to use the new forms schema, the documentation is a bit obsolete and I've just made it up to date based on the latest changes.
eYinka
force-pushed
the
forms-schema-adr
branch
from
0a2cbf9 to
84cbb9f
Compare
|
Thanks for the review @ryanb-gds I've updated those bits for clarity. |
eYinka
changed the title
eYinka
changed the title
2 participants
Following the refactor of configurable document type schema (from PR #10972), I've opened this PR to cover:
JIRA: https://gov-uk.atlassian.net/browse/WHIT-2788
This application is owned by the Whitehall Experience team. Please let us know in #govuk-whitehall-experience-tech when you raise any PRs.
Follow these steps if you are doing a Rails upgrade.