Treat attributes as a public data contract
Once a block is used in published content, its attributes are no longer an implementation detail. Existing posts may contain those values for years. Renaming an attribute, changing its type or changing how it maps to saved markup can affect old content, so schema decisions deserve the same care as a small API.
Prefer explicit values over overloaded strings
If one string contains several pieces of information separated by commas or custom delimiters, every consumer has to parse it and handle edge cases. Structured arrays and objects are easier to validate and extend. Booleans should represent real yes-or-no state rather than special string values such as ‘enabled’ and ‘disabled’.
Use defaults to improve editing, not hide missing data
A default can make a newly inserted block useful immediately, but it also changes how you distinguish an untouched value from an explicit user choice. For settings that affect meaning or external data, it can be better to require a deliberate selection and show a helpful empty state in the editor.
Plan repeated fields carefully
Repeated content such as features, team members or specification rows should have stable item shapes. If items can be reordered, avoid using array position as a long-term identity when another identifier would make updates safer. Keep presentational details out of each item when the same result can be achieved with block supports or theme styles.
- Store the minimum data needed to reproduce the content
- Keep field names stable and descriptive
- Avoid storing values that can be derived reliably at render time
- Document migrations when changing an established schema
Test old content before shipping schema changes
A block that works when newly inserted can still break existing posts. Keep representative fixtures from earlier versions and load them during development. If saved markup changes, provide a deprecation or migration path where appropriate instead of assuming every editor will manually rebuild the block.