Skip to content
Visit geeconglobal.com
Geecon Global
Menu

Schema Builder docs

Data for developers

How Schema Builder stores values, links and conditional fields, for website developers.

Each Schema Builder entry has a type (the schema ID) and a jsonField holding the values, keyed by field ID. Schema definitions, including each field's showWhen rule, are stored in the Schema Registry entry (registry format version 3), which uses the same content type with type set to SchemaRegistry.

Reading schemas from your website

  • Schema Builder saves the Schema Registry entry but doesn't publish it. To read schemas through the Delivery API, publish the Schema Registry entry after each schema change. Otherwise read it through the Preview API.
  • When you list Schema Builder entries, leave out the one whose type is SchemaRegistry.

Stored values

Text, numbers, booleans, dates and selects are stored as plain JSON values. See Field types for the exact format of each.

FieldValue in jsonField
Media, one{"sys": {"type": "Link", "linkType": "Asset", "id": "…"}}
Media, manya list of the above, in the editor's order
Reference, one{"sys": {"type": "Link", "linkType": "Entry", "id": "…"}}
Reference, manya list of the above
Repeatera list of objects keyed by sub-field ID
Conditionalunchanged: a hidden field's value stays as it was

Fetch linked assets and entries by ID. Contentful doesn't resolve or track links inside JSON fields, so include won't expand them.

Conditional fields (showWhen)

A field with showWhen: { field, values } is shown only when its controlling field matches:

Controlling fieldvaluesThe field is shown when
Boolean[true] or [false]the value is true / the value is not true (empty counts as not ticked)
Selectoption stringsthe value is one of the chosen options
Multi-selectoption stringsthe list contains at least one chosen option
  • The controlling field is a sibling: a top-level field for top-level fields, or a sub-field of the same Repeater for its sub-fields. Repeater sub-field rules are evaluated per item. A Repeater itself can only depend on top-level fields.
  • Chains are allowed. A field is visible only if its controlling field is visible and the rule matches.
  • Hidden values are still present in the JSON. Apply the rule before you use a value.

Developer exports

In Apps → Schema Builder, Developer exports (next to Create schema, or in a schema's actions menu) shows the saved schemas, not unsaved edits:

  • TypeScript: one file for all schemas, not including the Schema Registry entry. SchemaBuilderFields describes an entry's fields and narrows on type, so checking fields.type === "event" gives fields.jsonField the Event type. Links are typed as ContentfulLink, since Contentful doesn't resolve them.
  • JSON Schema: draft-07, for the chosen schema, including Repeater items. Date ranges use the ajv-formats keywords formatMinimum and formatMaximum: with Ajv, call addFormats(ajv, { keywords: true }). Other validators ignore them.
  • Sample entry: example jsonField data built from default values and placeholders. It may not match pattern rules.

Fields with a showWhen rule are optional in both the types and the JSON Schema, because a hidden field can be empty. Schema Builder doesn't validate hidden values, so apply the rule before you validate stored data against the JSON Schema.

Things to know

  • Data written through Contentful's API bypasses Schema Builder, so it isn't validated.
  • Contentful doesn't track links inside JSON, so a linked asset or entry can be unpublished or deleted without warning. Handle missing links in your website.