1. Content rendering

Field types in rendering data

When you build a component, you read field values from the fields object in the layout data and render them in your front-end app. Each field in fields has a Sitecore field type, and each field type produces a different JSON shape. Understanding these shapes is essential for building components that correctly read and render their content.

This topic describes the JSON shape of every built-in field type, where field values come from depending on the resolver configured on the rendering, and how component parameters differ from content fields.

Field structure

The value property

For field types such as Text, Rich Text, Number, Date, Checkbox, Image, General Link, File, and Droplist, the fields in the fields object contain the value property. value is a wrapper property that contains the raw, unrendered content of the field. Its type depends on the Sitecore field type. For most fields, the type is a string, but for Image and Link fields, it is a nested object. Note that the value property can also be an empty string "" or an empty object {}.

"FieldName": {
  "value": <TYPE_DEPENDENT_VALUE>
}

Field types such as Droplink, Droptree, Multilist, and Treelist don't have a value wrapper. Instead, the field key maps directly to an object {} or array [].

Important

Because a field can be present in fields but have no content, always check that the content is non-empty before rendering it.

The metadata property

When a page is rendered inside the SitecoreAI Page builder, an additional metadata property is included along with value. This property contains editor-specific metadata required to enable inline editing. It will be relevant when you set up visual editing and is not needed for rendering:

"FieldName": {
  "value": <TYPE_DEPENDENT_VALUE>,
  "metadata": { /* Editor metadata. Not needed for rendering. */ }
}

Where fields come from

The shape of the fields object in a component depends on the Rendering Contents Resolver configured on the component's rendering item in Sitecore. By default, fields come from the component's datasource item, but other resolvers can source content from the context item, children of the datasource, navigation hierarchies, and more. Understanding which resolver is in use tells you what shape of data to expect. For more information, see Content resolvers.

Field type reference

The following sections describe the JSON shape of each built-in Sitecore field type.

Single-Line Text and Multi-Line Text

Both text field types produce a plain string value:

"Heading": { "value": "Welcome to My Site" }

An empty field returns an empty string:

"Heading": { "value": "" }

Rich Text

A Rich Text field value contains HTML markup:

"Body": { "value": "<p>Hello <strong>World</strong></p>" }

Make sure to render a Rich Text value as raw HTML markup in your front-end app. Do not escape or encode it as a text string. If you do, HTML tags will appear as visible characters in the browser.

An empty field returns an empty string:

"Body": { "value": "" }

Number and Integer

Number and Integer field values are serialized as strings, not as JSON numbers:

"Price":    { "value": "29.99" }
"Quantity": { "value": "5" }
"Width":    { "value": "1200" }

Parse the string to a number before performing calculations.

An empty field returns an empty string:

"Price": { "value": "" }

Date and Datetime

Date and Datetime field values are strings in ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ), serialized to UTC by the Layout Service:

"PageDisplayDate": { "value": "2026-03-11T15:04:55Z" }

Internally, Sitecore uses the yyyyMMddTHHmmssZ format, but you won't encounter this in rendering data.

For a Date field, only the date portion is set by the content author. The time component is always T00:00:00Z:

"EventDate": { "value": "2026-03-11T00:00:00Z" }

For a Datetime field, both the date and time are stored:

"PublishedAt": { "value": "2026-03-11T15:04:55Z" }

An empty field returns an empty string:

"PublishedAt": { "value": "" }

Checkbox

A Checkbox field stores "1" when checked, or an empty string when unchecked:

"IsActive": { "value": "1" }   /* checked */
"IsActive": { "value": "" }    /* unchecked */

Test a Checkbox value only by checking whether the value property is "1". Do not compare against true, false, 0, null, or any other value.

Image

An Image field value is an object containing the media URL and image attributes. The src and alt properties are always present. The width and height properties are optional and may be absent entirely if not set by the content author. When present, width and height are strings, not numbers:

"FeaturedImage": {
  "value": {
    "src":    "/-/media/images/smart-speaker-1.jpg",
    "alt":    "Smart Speaker",
    "width":  "800",
    "height": "600"
  }
}

An empty field returns an empty object:

"FeaturedImage": { "value": {} }

Before rendering an image, check that value.src is a non-empty string.

A General Link field value is an object whose shape varies based on the linktype property. The General Link with search variant selects items using a search query but produces an identical JSON shape.

Before rendering an anchor element, check that value.href is a non-empty string.

Internal Link - links to a page within the site:

"PromoLink": {
  "value": {
    "id":          "{ITEM_GUID}",
    "anchor":      "",
    "target":      "",
    "linktype":    "internal",
    "text":        "View our products",
    "url":         "",
    "href":        "/en/products",
    "class":       "",
    "title":       "Products page"
  }
}

External Link - links to a URL outside the site:

"PromoLink": {
  "value": {
    "href":     "https://www.example.com",
    "text":     "Visit Example",
    "linktype": "external",
    "url":      "https://www.example.com",
    "target":   "_blank",
    "class":    "",
    "title":    ""
  }
}

Media Link - links to a file in the Sitecore Media Library:

"PromoLink": {
  "value": {
    "href":     "/-/media/files/brochure.pdf",
    "text":     "Download brochure",
    "linktype": "media",
    "id":       "{MEDIA-ITEM-GUID}",
    "class":    "",
    "title":    ""
  }
}

Email Link:

"PromoLink": {
  "value": {
    "href":     "mailto:[email protected]",
    "text":     "Contact us",
    "linktype": "mailto",
    "class":    "",
    "title":    ""
  }
}

An empty field returns an empty object:

"PromoLink": { "value": {} }

File

A File field value is an object containing the URL and display properties of the linked media item.

Before rendering a download link, check that value.href is a non-empty string.

"Attachment": {
  "value": {
    "src":         "/-/media/files/product-spec.pdf",
    "title":       "Product Specification",
    "displayName": "product-spec.pdf"
  }
}

An empty field returns an empty object:

"Attachment": { "value": {} }

Name Value List

A Name Value List field value is a plain string of ampersand-separated key=value pairs, exactly as stored in Sitecore.

To build a key-value map, parse the string by splitting on the ampersand & and then on the equal sign =.

The Name Value List is also the underlying field type used for Sitecore component parameters, which is why all values in params arrive as strings in key=value format before being deserialized into the flat params object.

"Styles": { "value": "theme=dark&size=large&layout=grid" }

An empty field returns an empty string:

"Styles": { "value": "" }

Droplist and Grouped Droplist

The Droplist and Grouped Droplist field types store the name of the selected item as a plain string, not a GUID and not a nested object. Droplist and Grouped Droplist are suitable when you only need the item name as a plain string value, for example as a category label or a CSS modifier. If you need to navigate to or render content from the referenced item, use Droplink or Droptree instead.

"Category": { "value": "news" }

An empty field returns an empty string:

"Category": { "value": "" }

The Droplink, Droptree, and Grouped Droplink field types store a reference to a single Sitecore item by its ID. Unlike Droplist and Grouped Droplist, which store only the item name, these field types resolve the referenced item and return its ID, URL, and a nested fields object containing its own content fields.

These fields do not use the { "value": ... } structure. The item object is returned directly at the field key, with no value wrapper. This is a distinct structure from field types such as Text, Image, and Link, which all wrap their content in value.

Before accessing fields, check that id is non-empty. The nested fields object contains the linked item's own fields, using the same field type shapes described in this topic.

"RelatedArticle": {
  "id":  "{ITEM-GUID}",
  "url": "/articles/my-article",
  "fields": {
    "Title":   { "value": "My Article Title" },
    "Summary": { "value": "A short summary." }
  }
}

An empty field returns an empty object:

"RelatedArticle": {}

Multilist, Checklist, Treelist, Taglist

This section describes the Multilist, Multilist with Search, Checklist, Treelist, Treelistex, Multiroot Treelist, and Taglist field types.

Sitecore stores the raw value of these field types as a pipe-separated list of item GUIDs, for example {GUID1}|{GUID2}|{GUID3}. The Layout Service resolves those GUIDs into item objects. This means that in rendering data, the value arrives as a direct array of item objects. Like Droplink and Droptree, these fields do not use the { "value": ... } structure:

"RelatedArticles": [
  {
    "id":  "{ITEM-GUID-1}",
    "url": "/articles/article-1",
    "fields": {
      "Title": { "value": "First Article" }
    }
  },
  {
    "id":  "{ITEM-GUID-2}",
    "url": "/articles/article-2",
    "fields": {
      "Title": { "value": "Second Article" }
    }
  }
]

An empty field returns an empty object:

"RelatedArticle": {}

The jsonValue property

The field shapes described in this topic apply to fields inside layout.item.rendered, which is the data your app receives from a layout GraphQL query.

When you retrieve item data through the item GraphQL query directly, field values are returned in a different wrapper that nests the field object inside a jsonValue property:

/* Layout query: */
"Image": {
  "value": { "src": "/-/media/images/logo.png", "alt": "Logo" }
}

/* Item query: */
"Image": {
  "jsonValue": {
    "value": { "src": "/-/media/images/logo.png", "alt": "Logo" }
  }
}

To read a field value safely in either context, you can programmatically check both properties:

imageValue = imageField.value if imageField.value exists
             else imageField.jsonValue.value if imageField.jsonValue exists
             else null

You can see this pattern applied when reading image and link fields in the Image component implementation in the Render Sitecore content in your app walkthrough.

Component parameters

Component parameters in params are distinct from content fields in fields. Unlike content fields, every parameter value is always a plain string, regardless of how the underlying Sitecore rendering parameter template field is typed:

"params": {
  "CSSClass":            "promo-primary",
  "EnabledPlaceholders": "1,2,3",
  "ColumnCount":         "3",
  "ShowImage":           "1"
}

Use the following patterns to handle values when reading params:

  • Boolean parameters - compare to "1" for truthy, and treat everything else, including a missing key, as falsy.
  • Numerical parameters - parse the string to a number before performing calculations.
  • Multi-value parameters - split on the comma , or the pipe symbol |, depending on convention. For example, the ColumnSplitter component's EnabledPlaceholders parameter is comma-separated. See how it is handled in the Render Sitecore content in your app walkthrough.
If you have suggestions for improving this article, let us know!