Schema Builder suits structured content that your website reads as a whole: settings, short lists and page blocks. It isn't built for content that you search, filter or sort by its own fields. This page helps you decide which of your content belongs in it.
At a glance
| Good fit | Not a good fit |
|---|---|
| Site settings and one-off content | Articles, blog posts and news |
| Short lists, such as FAQs, testimonials and office details | Product catalogues and listings filtered by their fields |
| Page blocks, such as a hero, a stats strip or a CTA band | Content translated field by field |
| Details that vary by category, such as product specs | Long rich-text pages |
| Short-lived campaign and landing-page content | Large data sets you query in many different ways |
Why: how your website reads entries
Every Schema Builder entry uses one content type, and its values are stored together in one JSON field. Contentful can filter these entries by schema (the type field) and by Title, but not by the values inside the JSON. So your website asks for "all entries of this schema", then reads, sorts or filters the values in its own code:
GET /entries?content_type=schemaBuilderEntry&fields.type=faq
That's quick and simple for settings and lists of up to a few hundred items. Contentful returns up to 1,000 entries per request. It doesn't work for questions like "posts tagged Design, newest first, page 3", which need Contentful to filter and sort inside the data.
Good fits, with examples
Site settings and one-off content
One entry per schema, which the website fetches by schema ID.
- Header and footer navigation, social links, contact details and company information
- A cookie banner, a maintenance or announcement bar, and default SEO tags
- Values that would otherwise sit in a config file and need a developer to change, such as support hours or the plan limits shown on a pricing page
Short lists
Fetch every entry of one schema and sort or filter it on the website.
- FAQs, testimonials, partner logos, office locations and team members
- An event's agenda, opening hours or a changelog
- For a list that belongs to one parent, use a Repeater field instead: the tiers of a pricing table or the steps of a recipe, all in one entry
Page blocks
Contentful plans limit how many content types a space can have, and each new one is a content model change. With Schema Builder, an admin can define a Hero, Stats strip, CTA band or Comparison table as a schema in minutes, and every block shares one content type.
Your regular Page content type links to blocks with an ordinary Reference field. Contentful resolves those links as usual, because each block is a normal entry.
Details that vary by category
Give each category its own schema, such as Laptop specs and Camera specs, and link the right one from a regular Product entry. Editors get a proper form with dropdowns and validation instead of a free-form box, and the website shows the details on the product page.
This works when the website displays the details. If shoppers need to filter products by them, such as "laptops with 16 GB of memory", use regular Contentful fields.
Campaign and landing-page content
Seasonal promotions, webinar pages and competitions are short-lived and come in one-off shapes. A schema is quicker to set up and retire than a permanent content type.
Limitations and what to do
| Limitation | What to do |
|---|---|
| Contentful can't filter or sort by values inside the JSON. | Fetch by schema and filter in your website. To look up one entry, such as a page by its slug, put that value in the entry's Title and filter on fields.title. |
Links inside the JSON aren't resolved by include. | Fetch linked assets and entries by ID. See Data for developers. |
| Values aren't translated field by field. | For short lists, add a Language select to the schema and filter in your website. For fully translated content, use regular Contentful fields. |
| Contentful can still publish an entry that the form shows as invalid. | Ask editors to clear every error before they publish, and check critical values in your website. |
| Data written through Contentful's API isn't validated by Schema Builder. | Validate imported data with the JSON Schema from Developer exports. See Data for developers. |
Still not sure?
Ask whether your website ever needs Contentful to find entries by a value inside them. If it does, use a regular content type for that content. If it only reads entries by type, or one at a time, Schema Builder will save you content types and give editors a validated form.