Data Model Reference

The Built.js data model is represented in a theme or plugin Next.js project by JSON data files in the public/data directory of the project.

Data files contain JSON data used for configuration of theme or plugin's pages, sections, plugins and more. They are kept in public/data.

These are the folders and files that you will find in this directory for a theme:

Here's a summary of how they work together:

1. global.json

• Contains site-wide settings like site name and logo.

2. theme.json

• Defines the theme's metadata, including namespace, title, description
• Lists required plugins and dependencies
• Specifies design system

3. sections.json

• Defines reusable page sections (e.g., homeSeo, homeLanding, header, footer)
• Each section has:
  • Configuration data
  • Template assignments
  • Type (head, body, or layout)
  • Collection references

4. templates.json

• Defines available templates for different components
• Includes metadata like category, namespace, and description
• References to actual component implementations

5. layout.json

• Defines the global layout structure
• Specifies order of sections (header, content, footer)

6. pages.json

• Lists all pages in the site

7. modules.json and module-pages.json

• Defines modular components that can be used across pages
• Maps modules to specific pages and positions

8. schemas/ directory

• Contains schema definitions for sections, content types, and global settings
• Provides validation and structure for the content

9. plugins/ directory

• Contains plugin-specific data configurations

The structure follows a modular, component-based architecture where:

• Global settings define site-wide configurations
• Sections are reusable components
• Templates define the visual implementation
• Modules provide functionality
• Everything is tied together through pages and layouts

This setup allows for:

• Easy theme customization
• Reusable components
• Flexible page layouts
• Plugin extensibility
• Clear separation of concerns between content, layout, and functionality

This is a more detailed breakdown of the data files:

Schema files

These files, located in public/data/schemas, create the definitions that will be used for Sanity schemas when the site is built.

• Content Type schemas
• Element schemas
• Global schema
• Section schemas

Content Type schema

A Content Type's schema is defined in public/data/schemas/content-types.json like this:

See Content Type data types for the data types that can be used for Content Type fields.

Example

{
  "contentTypes": [
     {
      "name": "author",
      "title": "Author",
      "dataPosition": 2,
      "fields": {
        "fullName": {
          "type": "string"
        },
        "slug": {
          "type": "uid",
          "targetField": "fullName",
          "required": true
        },
        "profile": {
          "type": "relation",
          "relation": "oneToOne",
          "target": "profile"
        },
        "posts": {
          "type": "relation",
          "relation": "oneToMany",
          "target": "post",
          "mappedBy": "author"
        }
      }
    }]
  }

https://github.com/richjava/corporate-basic/blob/main/public/data/schemas/content-types.json

Element schemas

An Element's schema is defined in public/data/schemas/elements.json like this:

See common data types for the data types that can be used for Element fields.

Example

{
  "elements": [
    {
      "name": "button",
      "title": "Button",
      "fields": {
        "slug": {
          "type": "uid",
          "targetField": "label",
          "required": true
        },
        "label": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      }
    }
  ]
}

https://github.com/richjava/corporate-basic/blob/main/public/data/schemas/elements.json

Global schema

A Global's schema is defined in public/data/schemas/global.json like this:

See common data types for the data types that can be used for Global fields.

Example

{
  "global": {
    "fields": {
      "name": {
        "default": "Corporate Tailwind",
        "type": "string"
      },
      "logo": {
        "type": "image"
      }
    }
  }
}

https://github.com/richjava/corporate-basic/blob/main/public/data/schemas/global.json

Section schema

A section's schema is defined in public/data/schemas/sections.json like this:

See Section data types for the data types that can be used for Section fields.

Example

{
  "sections": {
    "mainLanding": {
      "name": "mainLanding",
      "type": "body",
      "fields": {
        "preheading": {
          "type": "element",
          "repeatable": false,
          "element": "preheading"
        },
        "heading": { "type": "string" },
        "blurb": { "type": "text" },
        "image": { "type": "image" },
        "buttonLinks": {
          "type": "element",
          "repeatable": true,
          "element": "buttonLink"
        }
      }
    }
  }
}

https://github.com/richjava/corporate-basic/blob/main/public/data/schemas/sections.json

Data files

• Module data
• Module Page data
• Page data
• Section data
• Template data
• Collections data
• Layout data
• Global data
• App data

Module data

A Module is represents a business use case, like "Make Contact" but is usually named simply with one word (like "Contact"). Learn more about Modules here.

Module Data Model

The public/data/modules.json JSON file consists of a modules array. Each object in the array may have the following fields:

Example

public/data/modules.json

{
  "modules": [{
      "name": "introduce",
      "title": "Introduce",
      "description": "Familiarizes users with your product or service",
      "required": true,
      "modulePages": [{ "name": "homeBase" }]
    }]
}

https://github.com/richjava/corporate-basic/blob/main/public/data/modules.json

Module Page data

A Module Page contains a Page and a collection of Sections.

ModulePage Data Model

The public/data/module-pages.json JSON file consists of a modulePages array. Each object in the array may have the following fields:

Example

{
  "modulePages": [
    {
      "name": "contactBase",
      "page": {
        "name": "contact"
      },
      "sections": [
        {
          "name": "contactSeo",
          "position": 1
        },
        {
          "name": "contactLanding",
          "position": 2
        }
      ]
    }
  ]
}

https://github.com/richjava/corporate-basic/blob/main/public/data/module-pages.json

Page data

A Page represents a web page.

Page Data Model

The public/data/pages.json JSON file consists of a pages array. Each object in the array may have the following fields:

Example for a regular page

{
  "pages": [
    { "name": "home" },
    { "name": "services" },
    { "name": "contact" }
  ]
}

Example for an article page

{
  "pages": [{
      "name": "blogArticle",
      "contentType": {
        "name": "post",
        "config": {
          "populate": [
            {
              "name": "author",
              "populate": [
                {
                  "name": "profile"
                }
              ]
            },
            {
              "name": "tags"
            }
          ]
        }
      }
    }
  ]
}

https://github.com/richjava/corporate-basic/blob/main/public/data/pages.json

Section data

A Section is a main part of a website page. It contains one or more Templates.

Section Data Model

The public/data/sections.json JSON file consists of a sections array. Each object in the array may have the following fields:

Example

{
  "sections": [{
      "name": "team",
      "title": "Team",
      "description": "An informational section about the people in the company.",
      "templates": ["profileCards1"],
      "type": "body",
      "defaultTemplate": { "name": "profileCards1" },
      "data": { "heading": "Lorem ipsum dolor sit amet" },
      "collections": {
        "author": {
          "config": { "limit": 3, "populate": [{ "name": "profile" }] }
        }
      }
    }]
  }

https://github.com/richjava/corporate-basic/blob/main/public/data/sections.json

Template data

A Template represents the user interface of a Section. For example, the UI for a FAQ Section could be designed in a number of ways - an accordian, a list, etc. You can create a template for each of these designs and add them to your Section. Then in the Built Studio the end user of the Theme can decide which Template to use for the Section.

A Template contains a reference to a React component. A Template may contain Elements.

The public/data/templates.json JSON file consists of a templates array. Each object in the array may have the following fields:

Template Data Model

Example

{
  "templates": [{
      "name": "banner1",
      "title": "Banner 1",
      "category": "banners",
      "namespace": "richjava_corporate-basic",
      "description": "Full width banner with centered content.",
      "imageUrl": "https://res.cloudinary.com/dn7feeelf/image/upload/v1725878892/banner1_agmnah.png",
      "repoUrl": "https://github.com/richjava/corporate/blob/main/components/templates/banners/banner1.tsx"
    }
  ]
}

https://github.com/richjava/corporate-basic/blob/main/public/data/templates.json

Collections data

Collection data is kept in json files that have the plural name of the Content Type which defines the data fields, for example "authors.json".

The JSON file consists of a data array. Along with the data fields for a Content Type, each Entry object in a Collection array must contain the following three fields:

Example

{
  "data": [
     {
      "_id": "author-eb4f3b3c-04ed-4e08-b8fb-6b7db6efcb80",
      "_type": "author",
      "slug": "bob-brown",
      "fullName": "Bob Brown",
      "profile": "profile-fb4f3b3c-04ed-4e08-b8fb-6b7db6efcb60"
    }
  ]
}

https://github.com/richjava/corporate-basic/blob/main/public/data/collections/authors.json

Layout data

Layout specifies the header and footer and any otherf layout sections of a site.

Layout Data Model

The public/data/layout.json JSON file consists of a layout object with the following fields:

Example

{
  "layout": {
    "contentIndex": 1,
    "sections": [
      {
        "name": "header"
      },
      {
        "name": "footer"
      }
    ]
  }
}

https://github.com/richjava/corporate-basic/blob/main/public/data/layout.json

Global data

Global data is available to every page in the site. You can define the Global field names yourself.

The public/data/global.json JSON file consists of a global object with the fields defined in the Global schema file:

Example

{
  "global": {
    "name": "Blog Basic",
    "logo": {
      "url": "https://res.cloudinary.com/dn7feeelf/image/upload/v1725870579/builtjs_bert2m.svg",
      "path": "/images/builtjs.svg",
      "width": 45,
      "height": 45
    }
  }
}

https://github.com/richjava/corporate-basic/blob/main/public/data/global.json

App data

App data describes the theme or plugin. For a theme, this data is located in public/data/theme.json. For a plugin, it will be in public/data/plugin.json.

Shared Data Model for themes and plugins

The public/data/theme.json or public/data/plugin.json JSON file consists of a theme or plugin object with the following fields:

Theme-specific App Data

A theme also has the following field:

Example theme.json

{
  "theme": {
    "title": "Corporate Basic",
    "namespace": "richjava_corporate-basic",
    "description": "Small business theme with basic Tailwind styling.",
    "imageUrl": "https://res.cloudinary.com/dn7feeelf/image/upload/v1725878838/theme_tjckpi.png",
    "demoUrl": "https://builtjs-theme-corporate.vercel.app",
    "repoUrl": "https://github.com/richjava/corporate-basic",
    "designSystem": "basic"
    "plugins": ["richjava_blog-basic", "richjava_about-basic"],
  }
}

https://github.com/richjava/corporate-basic/blob/main/public/data/theme.json

Plugin-specific App Data

A plugin also has the following field:

Example plugin.json

{
  "plugin": {
    "namespace": "richjava_blog-basic",
    "title": "Blog Basic",
    "description": "Blog plugin with basic Tailwind styling.",
    "imageUrl": "https://res.cloudinary.com/dn7feeelf/image/upload/v1725870580/plugin_cqm0dq.png",
    "demoUrl": "https://builtjs-plugin-blog-basic.vercel.app",
    "repoUrl": "https://github.com/richjava/blog-basic",
    "mainModule": {
      "name": "blog"
    },
    "config": {
      "dependencies": ["date-fns"]
    }
  }
}

https://github.com/richjava/blog-basic/blob/main/public/data/plugin.json

If you haven't done so already, find out more about Built.js concepts.