JSON Schema Changes

README.md

I want to run through a few hypothetical scenarios because I'm still not 100% confident I understand how breaking changes will be handled in theme.json and also block.json.

block-json.md

block.json

theme-json.md

theme.json

In these scenarios "version": 1 was added with WP 5.8 and "version": 2 will be added in WP 5.9.

Scenario 1: Adding a property

settings.spacing.blockGap is added after the release of 5.8 and prior to 5.9. WordPress/gutenberg#33991

Is settings.spacing.blockGap available for use?

	"version": 1	"version": 2
WP 5.8	❌ Unavailable	❌ Invalid theme.json
WP 5.9	❌ Unavailable	✔️ Available
GB Plugin	✔️ Available after merge	✔️ Available after version is updated

Scenario 2: Renaming a property

settings.spacing.customMargin moves to settings.spacing.margin. WordPress/gutenberg#34349

(If the change won't actually happen as mentioned in the GB PR, let's say that it's a hypothetical scenario that may happen.)

Is settings.spacing.customMargin invalid and settings.spacing.margin valid? Has it been completely renamed?

	"version": 1	"version": 2
WP 5.8	❌ Unchanged	❌ Invalid theme.json
WP 5.9	❌ Unchanged	✔️ Renamed
GB Plugin	❌ Unchanged	✔️ Renamed

Scenario 3: Removing a property

settings.custom is removed and the recommendation is to just use CSS.

(I couldn't find a real scenario here, but I wanted to be complete, so I made up this scenario.)

Is settings.custom removed from use?

	"version": 1	"version": 2
WP 5.8	❌ Still present	❌ Invalid theme.json
WP 5.9	❌ Still present	✔️ Removed
GB Plugin	✔️ Property is ignored after merge	✔️ Removed after version is updated