Skip to content

JSON-Schema notes

SEK’s config surface is validated against generated JSON Schema (Draft-07) files rather than hand-maintained ones: the schema and the TypeScript types it’s generated from can never drift apart. This page covers section.schema.json, the one that validates the config every Config & YAML reference shape and every field-types catalogue entry comes from.

section.schema.json (at wp-content/plugins/section-editor-kit/schemas/section.schema.json) is generated from the plugin’s own TypeScript config types (SectionConfig), then post-processed: notably, loosening the sections/children field variants to accept either resolved SectionConfig[] objects or plain string[] handles, since YAML authors write handles and the runtime resolves them to objects. Two sibling schemas are generated alongside it from the same TypeScript source: post-type.schema.json (from PostTypeConfig) and field-type.schema.json (from FieldTypeConfig).

Freshness is enforced upstream: a check regenerates all three schemas into a temp directory and diffs them against the committed files: a mismatch means the plugin’s TypeScript config types changed without the schema being regenerated, and the check fails. If a table in the field-types catalogue ever looks stale, the fix is to regenerate the schema, never a hand-edit to either the schema or the generated fragment.

SectionConfigField (the discriminated union backing every entry in a section’s fields: list) compiles to a JSON Schema oneOf of 43 variants (at the time of writing), each pinning its type property to a single const value (e.g. { "const": "text" }) and setting "additionalProperties": false. A config value must therefore match exactly one arm, not merely be compatible with at least one, which is the correct semantics for a discriminated union: a field entry with type: 'text' and a select-only options.multiple key should fail validation, and oneOf (unlike anyOf) enforces that.

The field-types catalogue’s 43 generated fragments (at the time of writing) are produced by walking every arm of this oneOf, subtracting the properties shared with the base field shape, and rendering whatever type-specific properties remain as a table (or noting there are none). That derivation is the only mechanism this page surfaces: the fragment-generation pipeline itself is implementation detail, not something authors need to reason about when reading a table.