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.

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.

API Endpoint: Convert Simple Schema to Full JSON

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

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

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
    }
  }
}

Custom Rows

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

Simple Schema Relationships at a Glance

simple_template
  └── rows[] (simple_row)
         └── columns[] (simple_column)
                └── modules[] (discriminator on "type")
                        ├── simple_button
                        ├── simple_divider
                        ├── simple_image
                        ├── simple_html
                        ├── simple_list
                        ├── simple_menu
                        ├── simple_paragraph
                        ├── simple_title
                        └── [etc.]

• definitions.schema.json is referenced across almost all module and container schemas for styling props.

• Modules are polymorphic, distinguished by their "type" and validated using the oneOf structure in simple_column.

Which Schema Should You Use?

Schema Validation

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

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

noAnchorTags: (text: string): boolean =>
  !/<a[^>]*>[\s\S]*?<\/a>|<a\s*\/>/i.test(text),

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

Simple to Full JSON

Request Parameters

The API call accepts a template object, which is required to successfully perform the /simple-to-full-json API call. The following table describes this required object.

The following code snippet shows the template object as the body of the POST request.

Object Parameters Nested within the Template Object

The following table lists and describes both required and optional object parameters nested within the mandatory template object. This template object is the body of the POST request for the API call.

Settings Object Parameters

The following code snippet shows the optional settings object nested within the template object in the body of the POST request.

The following table lists and describes optional object parameters nested within the settings object. The settings object is nested within the mandatory template object.

Metadata Object Parameters

The following code snippet shows the optional metadata object nested within the template object in the body of the POST request.

The following table lists and describes optional object parameters nested within the metadata object. The metadata object is nested within the mandatory template object.

The following JSON Schema is related to the request parameters for this endpoint, as mentioned in the above table we accept only a template object, which is mandatory. The following JSON Schema describes the request parameters as well as the template object structure, going in depth on the possible properties of the template object.

Introduction

Schemas are structured definitions that describe the format, rules, and relationships of data within a system. They ensure consistency and validate inputs. In Beefree SDK, the Definitions Schema acts as a shared helper resource, providing reusable validation rules and enums across other content schemas such as rows, buttons, titles, and more. It does not represent a standalone content block but supports consistency and maintainability across the schema ecosystem.

Schema Overview

This section summarizes the purpose and key characteristics of the Definitions Schema.

• Schema Name: Definitions

• Purpose: Provides shared schema definitions used by other blocks for common properties like padding, border radius, border width, and module type.

• Usage Context: Referenced via $ref in other schemas to enforce value ranges and consistency.

• Related Schemas:

  • All content and layout schemas that use padding, border, or type enums (e.g., simple_row, simple_button, simple_title, etc.)

Structure Definition

Below is the JSON Schema definition and a detailed breakdown of each property.

JSON Schema

Field Descriptions

The following table lists the field descriptions along with their corresponding data type, and their description.

Additional Considerations

Consider the following when working with the Definitions Schema in Beefree SDK:

• Reusability: Always reference shared properties from this schema instead of redefining them.

• Consistency: Helps maintain uniform styling, validation, and developer experience across multiple content modules.

• Extensibility: New shared values (e.g., fontWeight, alignmentOptions, etc.) can be added here as the design system evolves.

Introduction

Schemas are structured definitions that describe the format, rules, and relationships of data within a system. They ensure consistency and validate inputs. In Beefree SDK, the Column object defines how individual columns are structured within rows across builders for emails, pages, and popups. It manages layout weight, background styling, padding, borders, and the content modules it contains. This documentation breaks down the column’s properties, requirements, and usage examples to help you implement and customize columns effectively.

Schema Overview

This section summarizes the purpose and key characteristics of the Column object.

• Schema Name: Column

• Purpose: Defines the layout and styling of a single column within a row, including spacing, background, and the modules it contains.

• Mandatory Fields: (None explicitly required in schema)

• Related Schemas:

  • definitions.schema.json (for padding and border definitions)

  • simple_row.schema.json (defines how columns are grouped in rows)

Structure Definition

Below is a representative structure of the Column object and a breakdown of each property.

JSON Object

Field Descriptions

The following table lists the field descriptions along with their corresponding data type, whether or not they are mandatory, and their description.

Usage Examples

Reference an example of the schema in the following code snippet.

Example Column

Additional Considerations

When working with Column objects in the Beefree SDK:

• Responsive Layouts: Use weight strategically to define flexible multi-column arrangements across devices.

• Styling: Combine background, border, and padding settings for visual structure and emphasis.

• Extensibility: Use customFields for non-standard properties.