Structured content

Structured content brings form-based editing to Experience Workspace. You define a schema, authors fill in a generated form in the structured content editor, and the result is delivered as JSON that your Edge Delivery Services blocks can consume. If you're familiar with JSON schema or form builders, then the concepts will feel familiar. Even if you're new to them, the structured content editor makes the concept approachable.

This document describes how to configured the feature so your authors can create structured content based on them and how developers can consume the resulting JSON data.

Configuring and creating structured content

To use structured content in your org, you must:

Fulfill the prerequisites
Create a folder to store your structured content
Enable the structured content editor
Create a schema
Create structured content based on that schema

Prerequisites

To set up and use structured content, you need:

An existing Edge Delivery Services project with Experience Workspace enabled, or the ability to create a new one
Ability to configure the editor.path setting in the organization configuration
Content author permissions for the site to create folders, documents, and schemas

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

Create structured content storage

Structured content documents are stored in your project's content tree in Experience Workspace in their own dedicated folder.

Navigate to your project in Experience Workspace at https://da.live/#/<ORG>/<SITE>.
Create a new folder with a simple, meaningful name (e.g. /forms, /products). For our example, we will create the folder /coffees.

This folder will store all your structured content documents.

Enable the structured content editor

Experience Workspace must know that it should use the structured content editor whenever you create or edit documents in the folder you created in the previous step to store your structured content. This is done by adding a configuration entry that maps a folder path to the structured content editor URL.

Open the Experience Workspace config at https://da.live/config#/<ORG>/.
Add a new config entry with the following values:

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

To use the structured content editor for multiple folders, simply add multiple editor.path entries.

Create a schema

Now that you have a place to store your structured content, you need to define the structure of the content. Schemas define the structure of your content and are created using the Schema Editor app.

Open the Schema Editor app at https://da.live/apps/schema.
Enter your organization and site in the format /<ORG>/<SITE> and click Load schemas.
If you have not created a schema before, enter the name (in our example coffee), otherwise use the dropdown menu to select New schema and enter the schema name.
Define your schema following the Experience Workspace structured content definition. Use the sample coffee schema in the document Schema for structured content.
1. The Schema Editor app validates the schema as you type. You can not save until it passes validation.
Click Save schema.

Note: Schemas are stored as documents under /<ORG>/<SITE>/.da/forms/schemas/, but they are only visible and manageable through the Schema Editor app.

Create structured content using your schema

Navigate to your structured content folder at https://da.live/#/<ORG>/<SITE>/<FOLDER_NAME>.
Click the plus icon and then select Document to create a new document.
Give your document a name. In this example we will call it morning-muse-light-roast.
Select the schema you already created. In this example we can choose Coffee Product.
Click Create.
The structured content editor opens, presenting your schema as a form for the author to complete. Provide the required data.
Click Send and then Publish to publish.

Once published, your structured content can be consumed as JSON. Blocks on your Edge Delivery Services site can fetch structured content as JSON using the delivery endpoint.

See the authoring documentation about structured content for more details on the editor.
See the Schema for structured content document for more details on schema.
See the remainder of the current document for more details on how to consume the JSON.

Delivery endpoint

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

Endpoint Format

https://da-sc.adobeaem.workers.dev/<ENVIRONMENT>/<ORG>/<SITE>/<PATH_TO_DOCUMENT>

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

For example, you could access the document offer using this cURL call.

curl 'https://da-sc.adobeaem.workers.dev/live/aemsites/da-frescopa/forms/offer'

Accessing protected content

The delivery API supports authenticated access, so it can serve content from protected sites and paths. If your content is protected, the client must first complete the site authentication setup to obtain a token. Refer to the document Authentication setup for a site for details on site authentication.

Once you have a token, pass it in the authorization header (replace hlx__TOKEN with your token):

GET https://da-sc.adobeaem.workers.dev/<ENVIRONMENT>/<ORG>/<SITE>/<PATH_TO_DOCUMENT>
authorization: token hlx__TOKEN

Listing and querying structured content

The delivery endpoint returns one structured content document at a time. When a block needs to render a list across many documents (or to filter, sort, or project specific fields without downloading each document one by one), configure a query index.

The index runs as part of the Edge Delivery Services pipeline and produces a single JSON file at a path you choose, listing one row per included document with whichever properties you extract. The resulting JSON is publicly cacheable, so the same index can be consumed by Edge Delivery Services blocks and by external clients.

Define indices in helix-query.yaml at the root of your project's GitHub repository. See the document Indexing reference for the full schema.

The recommended selector pattern is key-anchored. The form editor renders each property key as an element with an id matching that key. Select properties by key name with :has().

version: 1
indices:
  products:
    target: /products-index.json
    include:
      - /products/**
    exclude:
      - "**/fragments/**"
      - "**/drafts/**"
      - "**/*.json"
    properties:
      name:
        select: div > div > div:has(#name) > div:last-child
        value: textContent(el)
      price:
        select: div > div > div:has(#price) > div:last-child
        value: textContent(el)
      status:
        select: div > div > div:has(#status) > div:last-child
        value: textContent(el)
      inStock:
        select: div > div > div:has(#inStock) > div:last-child
        value: textContent(el)

This produces an index at https://main--<REPO>--<OWNER>.aem.live/products-index.json with name, price, status, and inStock extracted for every product document under /products/.

Page metadata and indexing

When a structured content page is published it behaves like any other Edge Delivery Services page: it can be crawled, it appears in query-index.json, and it can be listed in sitemap.xml. The structured content editor does not expose a way to set page-level metadata (for example robots: noindex, nofollow, a canonical URL, or a custom title/description). This is because page metadata is a property of the page, not of your schema's data. In fact, the keys metadata and section-metadata are reserved in schemas (see the schema specification) precisely so your data never collides with the page's metadata block.

If you need to keep certain structured pages out of search results or out of the sitemap, use either a metadata block or the bulk metadata sheet.

Metadata block

Open the document in the standard Experience Workspace editor rather than the structured data editor. Do this by replacing the #form in the URL with #canvas. For example, if you are editing the following structured data in the structured data editor

https://da.live/form#/bohnertchris/da-harvey-dent/coffees/morning-muse-light-roast

Change the URL to

https://da.live/canvas#/bohnertchris/da-harvey-dent/coffees/morning-muse-light-roast

Once you are editing your structured data in the normal Experience Workspace editor, use Content mode and add a metadata block. This is added as a two-column table whose first row is the word metadata. Each subsequent row is a key/value pair.

`metadata`
`robots`	`noindex, nofollow`
`title`	`Morning Muse Light Roast`
`description`	`A bright, citrusy light roast with a smooth finish`

Once the structured data document is published, this metadata block renders as <meta name="robots" content="noindex, nofollow"> (and the corresponding title/description tags) in the page <head>.

Bulk metadata sheet

To apply metadata to many structured pages at once, create or edit a bulk metadata sheet (commonly /metadata) with a URL column that matches a path pattern. For example, to keep an entire folder out of search engines:

`url`	`robots`
`/products/drafts/**`	`noindex, nofollow`

See the document Bulk Metadata for the sheet format and matching rules.

Keeping pages out of the sitemap and query-index

robots: noindex tells search engines not to index the page, but does not by itself remove it from a generated sitemap.xml.

To exclude pages from query-index.json (and therefore from a sitemap derived from it), add an exclude glob in helix-query.yaml (see the example in the previous section). Configure the sitemap itself via helix-sitemap.yaml (see the document Sitemap for details).

Limitations

Using $ref / $defs can produce recursive structures. To prevent infinite loops the implementation limits expansion to 10 levels. Prefer flattening deeply nested structures.

For the full set of supported and unsupported constructs, see schema-spec.md.

Troubleshooting

Structured content editor not loading

Verify the editor.path config in your Experience Workspace config is correct.
Ensure the folder path matches exactly ( it is 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.
Check the delivery endpoint URL format.
Ensure <ENVIRONMENT> is live for published content or preview for preview content.

A field's value is missing from the delivered JSON

Empty strings, empty arrays, and empty objects are treated as absent and stripped on save. Fill the field with a real value.
Confirm the property key matches your query-index selector exactly (selectors are key-anchored).