Structured Content

This guide will help you configure an existing Edge Delivery Services project with Document Authoring to use the Structured Content feature, enabling schema-based content editing and JSON data delivery.

Structured Content brings form-based editing to Document Authoring, allowing you to define schemas and create structured data that can be consumed as JSON by your Edge Delivery Services blocks. If you're familiar with JSON Schema or form builders, you'll find the concepts familiar—but even if you're new to these tools, the guided interface makes it approachable.

Key Concepts

Before you begin, here are a few important concepts:

Schemas define structure. Every structured content document is based on a schema that defines what fields are available and how they're organized.
The editor has two panels. The Navigation panel shows your content hierarchy, while the Editor area provides full-width forms for each section.
Changes auto-save. Unlike traditional forms, your content is automatically saved as you type—no save button needed.
Data is delivered as JSON. Published content is automatically available via a JSON endpoint for your blocks to consume.

Overview

Structured Content allows you to:

Define content schemas using JSON Schema
Edit structured data through a form-based editor
Deliver content as JSON for consumption by blocks on your Edge Delivery Services site
Preview and publish structured content

Prerequisites

Required Access and Permissions

To set up and use Structured Content, you need:

An existing Edge Delivery Services project with Document Authoring enabled, or the ability to create a new one
Organization Administrator role to configure the editor.path setting
Content Author permissions for the site to create folders, documents, and schemas

If you don't have the required permissions, contact your Document Authoring organization administrator to request access.

Setup Steps

1. Create or Use an Existing Edge Delivery Services Project

If you don't have an Edge Delivery Services project yet, follow the official tutorial at https://www.aem.live/developer/tutorial

2. Configure Structured Content Storage

Structured content documents are stored in your project's content tree in Document Authoring.

Create a dedicated folder:

Navigate to your project in Document Authoring at https://da.live/#/<ORG>/<SITE>
Create a new folder (e.g., /forms, /data, or any custom name)
This folder will store all your structured content documents

Enable the Structured Content Editor:

You must configure Document Authoring to use the Structured Content editor for documents in your chosen folder. This is done by adding a configuration entry that maps folder paths to the editor URL.

Open the Document Authoring config page: https://da.live/config#/<ORG>/ (requires Organization Administrator role)
Add a new config entry with the following:

key	value
`editor.path`	`/<ORG>/<SITE>/<FOLDER_NAME>=https://da-sc--da-live--adobe.aem.live/form#`

Example:

key	value
`editor.path`	`/aemsites/myproject/forms=https://da-sc--da-live--adobe.aem.live/form#`

This configuration tells Document Authoring: "For any document created in the /aemsites/myproject/forms folder, open it with the Structured Content editor instead of the default Document Authoring editor."

Multiple Folder Configuration:

If you want to use the Structured Content editor for multiple folders, add multiple entries separated by commas:

key	value
`editor.path`	`/aemsites/myproject/forms=https://da-sc--da-live--adobe.aem.live/form#`
`editor.path`	`/aemsites/myproject/data=https://da-sc--da-live--adobe.aem.live/form#`

3. Create a Schema

Schemas define the structure of your content and are created using the Schema Editor app.

Creating a new schema:

Open the Schema Editor app: https://da.live/apps/schema
Use the dropdown menu to select "New Schema"
Define your schema structure (see JSON Schema Details below)
Save the schema

Note: Schemas are automatically saved as documents under your <ORG>/<SITE> path in the content repository. However, schemas are only visible and manageable through the Schema Editor app.

4. Create Your First Structured Content Document

Navigate to your structured content folder: https://da.live/#/<ORG>/<SITE>/<FOLDER_NAME>
Click "New" to create a new document
Give your document a name

5. Select a Schema

When the Structured Content editor loads:

As an author, you'll be prompted to select one of your created schemas
Choose the appropriate schema for your content type
The form-based editor will load with fields corresponding to your schema

6. Editing Your Content

The Structured Content editor is designed to make managing complex data structures straightforward. It consists of two main components:

Navigation Panel:

Reflects the structure of your content with nested elements in a tree view
Provides click-and-jump functionality to navigate to any section in the editor
Displays validation insights to help identify issues in your content
Offers basic operations for managing list-type elements (add, remove, reorder)

Editor Area:

Provides a flat visualization of the complete data structure
Uses the full width of the editor area for managing any section in the hierarchy
Shows all fields for the current section with appropriate input controls

As an author, you can:

Manage the structured content through the form-based editor
Navigate between sections using the tree view
Changes are automatically saved as you type

7. Preview and Publish

When you preview or publish your document:

Use the standard Preview or Publish buttons in the editor
You'll be redirected to the delivery URL
The page displays an overview of your structured data
The same URL can be used by blocks to fetch JSON data

8. Consume Data in Blocks

Blocks on your Edge Delivery Services site can fetch structured content as JSON using the delivery endpoint.

Delivery Endpoint

Once your content is published, it becomes available as JSON through a delivery endpoint. This is how your Edge Delivery Services blocks will fetch the structured data.

Endpoint Format

https://mhast-html-to-json.adobeaem.workers.dev/<ENVIRONMENT>/<ORG>/<SITE>/<PATH_TO_DOCUMENT>

Parameters:

<ENVIRONMENT>: Either live (for published content) or preview (for preview content)
<ORG>: Your organization name
<SITE>: Your site name
<PATH_TO_DOCUMENT>: Path to your document (without file extension)

Example

curl 'https://mhast-html-to-json.adobeaem.workers.dev/live/aemsites/da-frescopa/forms/offer'

Note: The delivery endpoint URL may change in the future. We will communicate any changes through official channels.

Working with Schemas

Schemas are the foundation of structured content—they define what fields are available, what types of data they accept, and how they're organized.

Schema Format

Structured Content uses JSON Schema to define data structures. The Schema Editor app provides a visual interface for creating schemas.

Schemas can be defined using:

Inline definitions: Properties defined directly in the schema
$ref / $defs definitions: Reusable schema components referenced by path

Best Practices

Use descriptive titles:

sample (json)

{
  "type": "object",
  "title": "Product Information",
  "properties": {
    "name": {
      "type": "string",
      "title": "Product Name"
    },
    "price": {
      "type": "number",
      "title": "Price (USD)"
    }
  }
}

The title properties are displayed in the editor UI. If omitted, the property key will be used as-is.

Keep schemas simple:

Use straightforward object and array structures
Avoid overly complex nesting when possible
Leverage $defs for reusable components

Limitations

Maximum Depth Level

Using $ref / $defs definitions can lead to recursive structures. To prevent infinite loops:

The current implementation limits the depth level to 10 levels
This value is experimental and may change in future releases
Consider flattening deeply nested structures when possible

Supported JSON Schema Features

The Structured Content editor supports:

✅ Basic types: string, number, boolean, integer
✅ Objects and nested objects
✅ Arrays of items
✅ $ref and $defs for reusable definitions
✅ Common validation keywords: required, enum, pattern, minLength, maxLength

Not currently supported:

❌ oneOf / allOf / anyOf complex schemas
❌ Deep nesting beyond 10 levels
❌ Some advanced JSON Schema validation keywords

If you need features not currently supported, please reach out to discuss your use case.

Example Workflow

Below is a complete example that walks through setting up a simple product catalog. This will give you a sense of how all the pieces fit together.

Create folder: /products in your Document Authoring organization/site

Configure editor path in Document Authoring config:

/<ORG>/<SITE>/products=https://da-sc--da-live--adobe.aem.live/form#

Create schema: "Product" with fields for name, description, price, and specifications

Example schema:

schema (json)

{
  "type": "object",
  "title": "Product",
  "required": ["name", "price"],
  "properties": {
    "name": {
      "type": "string",
      "title": "Product Name"
    },
    "description": {
      "type": "string",
      "title": "Description"
    },
    "price": {
      "type": "number",
      "title": "Price (USD)",
      "minimum": 0
    },
    "specifications": {
      "type": "object",
      "title": "Specifications",
      "properties": {
        "brand": {
          "type": "string",
          "title": "Brand"
        },
        "model": {
          "type": "string",
          "title": "Model"
        },
        "weight": {
          "type": "number",
          "title": "Weight (kg)"
        }
      }
    },
    "inStock": {
      "type": "boolean",
      "title": "In Stock"
    }
  }
}

Create document: /products/laptop-pro
Edit content in the form-based editor
Publish the document
Fetch data from your block:

sample (javascript)

const response = await fetch(
  'https://mhast-html-to-json.adobeaem.workers.dev/live/<ORG>/<SITE>/products/laptop-pro'
);
const product = await response.json();

Troubleshooting

Below are solutions to common issues you may encounter.

Structured Content editor not loading

Verify the editor.path config in your Document Authoring config is correct
Ensure the folder path matches exactly (case-sensitive)
Confirm you have Organization Administrator permissions to modify the configuration
Clear browser cache and try again

Schema not appearing in Schema Editor app

Check that the schema was saved successfully
Verify you have Content Author permissions for the site
Refresh the schema list in the Schema Editor app

Data not fetching from delivery endpoint

Verify the document has been published (not just saved)
Check the delivery endpoint URL format
Ensure <ENVIRONMENT> is set to live for published content or preview for preview content