Simple Schema

Learn more about how to use Beefree SDK's simple schema for AI-driven design.

Simple Schema Features by Plan Type:

• Superpowers & Enterprise Plans: Access to Simple Schema for Custom AddOns and Custom Rows.

• All Paid Plans: Access the Simple Schema API through the Content Services API (CSAPI).

Overview

Beefree JSON is the JSON schema we use to structure and validate designs within Beefree SDK. It's a very comprehensive and complex schema and for this reason, it does not provide the best structure for training AI models in workflows that include AI-driven design creation. Beefree SDK's Simple Schema is a lightweight alternative that's more accessible for AI engines (and humans).

As a simpler model, Simple Schema is an intuitive language you can use as a baseline for training AI agents and building templates programmatically outside of Beefree SDK's visual builders. These headless templates can then be instantly transformed into Beefree’s native JSON and loaded inside the builder for end users to edit accordingly in a no-code environment.

You can convert the simple schema into native Beefree JSON using the Content Services API endpoint /v1/conversion/simple-to-full-json.

Simple Schema also enhances Custom AddOns development by:

• Providing a comprehensive set of properties for full flexibility in your design.

• Consolidating the Custom Rows, Single Content AddOn, and Row Mixed schemas into a unified, compatible schema type.

Reference the Simple Schema GitHub repository for more information.

Simple Unified Schema

There are two ways you can use the schemas available in the documentation and the GitHub repository to implement Simple Schema.

These approaches are:

• Use the Simple Unified Schema. This option allows you to use one reference file to structure your templates and validate them prior to sending them to the endpoint. Learn more about the Simple Unified Schema in the Simple Schema GitHub repository.

• Use the individual, but connected, simple schemas for templates, rows, columns, and modules. This option allows you to use multiple focused schema files to structure your templates and validate them prior to sending them to the endpoint. These schemas are detailed in the subsequent pages.

Webinar

The following webinar includes an in-depth exploration of Simple Schema, the /simple-to-full-json API endpoint, and covers two example scenarios and applications of Simple Schema.

API Endpoints: Convert Simple Schema to Full JSON (or the other way around)

You can convert Simple Schema into fully functional Beefree native JSON using the following endpoint:

POST /v1/conversion/simple-to-full-json

Or you can use the following endpoint to turn an existing Beefree design (Full JSON) into the Simple Schema:

POST /v1/conversion/full-to-simple-json

These endpoints are essential for building headless template workflows, where templates are generated, assembled, or adjusted programmatically—by AI models, config files, or external systems—and later converted for use inside the builder.

Visit the Content Services API Simple to Full JSON and Full to Simple documentation to learn more about how to use these endpoints.

Tip: Reference an example valid request body in the GitHub repository to experiment with the API endpoint and see it in action.

Use Cases

The following section lists several ways you can leverage Simple Schema to bring additional value to your end users.

AI-Powered and Headless Template Creation

Build a chatbot or frontend tool where users describe what they want. An AI model creates a Simple Schema layout, which you convert to Beefree JSON using the API. Load the result into the builder—or send it directly into a campaign—without ever touching the editor during creation.

For example, your dev team can build a frontend that lets users describe their design (email, page, or popup), and submit that description to an AI agent on the frontend. On the backend:

1. The prompt is processed by an AI model trained to produce a template using Simple Schema.

2. You pass the schema to /v1/conversion/simple-to-full-json.

3. You receive Beefree native JSON, which is then loaded directly into the Beefree SDK builder.

This approach blends AI-driven design creation and your own custom user interface, which supports your end users in not starting their content creation workflow from scratch, but rather from an AI-generated design.

A/B Testing and Variations

Use schema generation logic to produce slightly varied layouts for testing. Combine this with AI or custom logic to automatically create multiple variants of templates.

Custom Validation Workflows

Enforce validation rules that check your schema structure or inputs to meet your unique business or design standards.

Fully Headless Workflows

Simple Schema lets you build and manage complete email, page, and popup templates without ever opening the visual builder. Use it for content generation, programmatic campaigns, template marketplaces, or internal automation systems.

Custom AddOns

Simple Schema enhances the development experience for Custom AddOns by integrating new properties that foster an additional layer of customization.

Developer Notes:

• All AddOn content types now rely on Simple Schema.

• The locked property is only enforced inside Row AddOns to avoid poor UX in single-content modules.

• Use the text field consistently for content across all textual modules.

• Default values will be applied if specific properties are omitted in the Simple JSON.

Content Dialog Handler Behavior

To develop your own Custom AddOn, you need to utilize Beefree SDK's Content Dialog method. The following code snippet provides and example of how to utilize the Content Dialog for Custom AddOns with Simple Schema.

{
  "contentDialogId": "addOnID",
  "value": {
    "blockStyle": {
      // Padding, hover styles, and other block-level styling
    }
  }
}

Tip: The structure in the code snippet supports consistent block-level styling globally.

Custom Rows

Simple Schema provides a comprehensive set of properties for customizing and creating Custom Rows.

Which Schema Should You Use?

Scenario	Schema(s) to Use
Client-side validation	Any individual module schema (simple_button, simple_list, etc.)
Saving a full template	simple_template.schema.json (including rows, columns, and modules)
API endpoint schema	Request body can directly use simple_template
Database modeling	Use nested object structure defined in simple_template, with shared fields via $refs

Schema Validation

The following code snippet provides an example of custom Simple Schema fields for merge tag support, and custom validations.

urlOrMergeTagsOrEmpty: (text: string): boolean => {
      try {
        if (text === '') {
          return true
        }
        new URL(text)
        return true
      } catch (e) {
        return /{{.*}}/.test(text)
      }
    },

These validators ensure generated content is correct and aligns with the data structure defined within the Simple Schema.