Configure JSON-LD schemas

Create the schema container

Each site that uses JSON-LD schemas requires its own Schema item. SXA doesn't create this item automatically.

To create the container:

1. In the Content Editor, navigate to your site's Settings item. The exact path depends on your site's structure.

2. Create an item named Schema using the /sitecore/templates/Foundation/JSS Experience Accelerator/JSON-LD/Mapping/Schema template. The resulting path is:

   /sitecore/content/<site collection>/<site>/<Settings>/Schema

3. Save the item.

Under this container, configure the page, rendering, or site mappings your site needs. Creating the container alone doesn't populate schema properties.

When selecting schema types and properties, use the predefined definitions under:

/sitecore/system/Settings/Foundation/JSS Experience Accelerator/JSON-LD/Schemas/

Select properties from the chosen schema definition instead of entering Schema.org property names manually.

Configure page schemas

A page schema maps a page template and its fields to a schema type and properties.

To configure a page schema:

1. Under your site's Schema item, create a Template Schema item for the page template you want to map.

2. Configure the following fields:

   Field	Value
   Schema	The predefined schema definition, such as Article.
   Template	The Sitecore page template to which the mapping applies.

3. Under the Template Schema item, create a Template Schema Property item for each field you want to expose.

4. For each property item, configure the following fields:

   Field	Value
   Template Field	The Sitecore field that supplies the value.
   Schema Property	One or more properties from the selected schema definition.

5. Save your changes.

For example, to map an article page's title and summary:

• Template Schema: Article Page
  • Schema: Article
  • Template: Article Page
    • Template Schema Property: Title
      • Template Field: pageTitle
      • Schema Property: headline
    • Template Schema Property: Summary
      • Template Field: summary
      • Schema Property: description

For pages that use the selected template, or a template that inherits from it, the resolver reads the mapped fields and adds their non-empty values to the schema object.

Configure rendering schemas

Rendering schemas use the same Template Schema and Template Schema Property items as page schemas, but map the rendering's data source template instead of a page template.

To configure a rendering schema:

1. Under your site's Schema item, configure a Template Schema mapping for the rendering's data source template, as described in Configure page schemas.
2. Add Template Schema Property children for the data source fields you want to expose.
3. On the page, select the rendering instance and enable the Include in schema rendering parameter.
4. Save your changes.

The resolver uses the rendering's data source item to find a matching template mapping and build the schema. A rendering contributes a schema only when it has a data source, has a matching template mapping, and has Include in schema enabled.

Configure site schemas

Use site schemas for values that apply independently of a page template or rendering, such as organization information.

To configure a site schema:

1. Under your site's Schema item, create a Site Schema item.

2. In the Schema field, select a predefined schema definition, such as Organization.

3. Under the Site Schema item, create a Site Schema Property item for each property you want to populate.

4. For each property item, configure the following fields:

   Field	Value
   Schema Property	A property from the selected schema definition.
   Value	A static value or an SXA token, such as $sitelang.

5. Save your changes.

For example:

• Site Schema: Organization
  • Schema: Organization
    • Site Schema Property: Name
      • Schema Property: name
      • Value: Example Organization
    • Site Schema Property: URL
      • Schema Property: url
      • Value: https://www.example.com

The resolver combines the properties under one Site Schema item into a single schema object. If a token resolves to an empty value, the resolver omits that property.

Render JSON-LD in your application

The Layout Service includes resolved schemas in the sitecore.context.schemas array. For example, a page schema and a site schema can produce the following context data:

{
  "sitecore": {
    "context": {
      "schemas": [
        {
          "@context": "https://schema.org",
          "@type": "Article",
          "headline": "A page title",
          "description": "A page summary"
        },
        {
          "@context": "https://schema.org",
          "@type": "Organization",
          "name": "Example Organization",
          "url": "https://www.example.com"
        }
      ]
    }
  }
}

This example shows only the context portion of the response. Schemas don't change the Layout Service route structure. When the resolver can't resolve any schemas, it omits the schemas property.

The rendering host must add the JSON-LD script to the page. See the following example:

const schemas = layoutData?.sitecore?.context?.schemas;

{schemas?.length > 0 && (
  <script type="application/ld+json">
    {JSON.stringify(schemas)}
  </script>
)}

Verify the output

To check your configuration:

1. Request Layout Service data for a page that uses your configured mappings.
2. Check that sitecore.context.schemas contains the expected schema types, properties, and values. If the property is absent, check the site's Schema container, template mappings, and, for rendering schemas, the data source and Include in schema parameter.
3. Inspect the rendered page HTML and confirm that the application/ld+json script contains valid JSON with the expected data.
4. Validate the structured data with the Schema Markup Validator and, for Google search features, the Rich Results Test.

Search engines can require specific properties for enhanced results. Configure the properties required for your schema type and validate the final rendered page, not only the Layout Service response.

Schema resolution rules

• Each schema object includes @context with the value https://schema.org and the configured @type.
• The resolver omits empty Sitecore field values.
• Only properties defined under the selected schema definition are available for mapping.
• Template mappings apply to the selected template and templates that inherit from it.
• If multiple sources produce the same @type, the schema with more populated properties takes precedence.
• Page editing mode doesn't disable schema resolution.

Limitations

The JSON-LD configuration supports scalar field values and site-level static or token-resolved values. It doesn't build nested objects, such as an author object with its own @type and properties.

The feature doesn't provide:

• Real-time validation against Schema.org or search-engine requirements.
• A JSON-LD preview in Pages.
• MVC or other non-headless output.
• Per-language schema configuration.
• Automatic schema generation without explicit configuration. Rendering schemas also require Include in schema to be enabled.