Skip to content
Visit geeconglobal.com
Geecon Global
Menu

Schema Builder docs

When to use it

What Schema Builder suits best, with examples, what it isn't built for and how to work within its limits.

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 fitNot a good fit
Site settings and one-off contentArticles, blog posts and news
Short lists, such as FAQs, testimonials and office detailsProduct catalogues and listings filtered by their fields
Page blocks, such as a hero, a stats strip or a CTA bandContent translated field by field
Details that vary by category, such as product specsLong rich-text pages
Short-lived campaign and landing-page contentLarge 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

LimitationWhat 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.