---
title: "Data source resolution"
manual: "Handlebars"
version: "main"
permalink: "https://docs.typo3.org/permalink/cpsit/typo3-handlebars:developer-corner-data-sources@main"
source: "DeveloperCorner/DataSources.rst"
rendered: "2026-09-29T09:05:57+00:00"
---

# Data source resolution {#developer-corner-data-sources}

This page describes in detail how data sources are resolved. It complements
the introduction in [Data sources](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:usage-data-sources@main) and is relevant when combining
nested processors or implementing a
[DataSourceAwareProcessor](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:developer-corner-data-source-aware-processor@main).

-   [Availability](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:availability@main)
-   [Priority order](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:priority-order@main)
-   [Nested keys](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:nested-keys@main)
-   [Payload resolution](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:payload-resolution@main)

## Availability {#developer-corner-data-sources-availability}

Not every data source is available in every context, and not every source
necessarily holds what its name suggests:

-   A processor invoked through TYPO3's `dataProcessing` chain
    always receives a `contentObjectConfiguration`. Once it is
    nested inside another processor's own `dataProcessing`, that
    value is no longer the top-level `HANDLEBARSTEMPLATE`
    configuration — it is whatever the parent processor forwards instead
    (e.g. `currentValue`).
-   The collection built for `HANDLEBARSTEMPLATE`'s own
    `preProcessing`/`postProcessing` hooks sets only
    `contentObjectRenderer` and `processorConfiguration`;
    `contentObjectConfiguration` and `processedData`
    are absent there.

## Priority order {#developer-corner-data-sources-priority}

When a lookup is not restricted to a specific source, all sources that are
actually available are searched in priority order, highest first:

1.  `processorConfiguration`
1.  `processedData`
1.  `contentObjectRenderer`
1.  `contentObjectConfiguration`

The first source that has the requested key wins; sources are never merged
for this kind of lookup. This is why an option like `table`, set
by an outer processor, can be picked up by a nested processor without being
repeated explicitly — as long as the nested processor actually queries that
source (some processors restrict a given option to a specific source, or a
specific subset, rather than searching all four).

## Nested keys {#developer-corner-data-sources-nested-keys}

A lookup key may use `/` to reach into a nested array within a
single data source, e.g. `some/nested/key`. Each segment is
looked up literally, one level at a time; the lookup fails (and any
configured default value is used) as soon as one segment does not exist.

A key is otherwise always matched literally, dots and all. This matters for
raw TypoScript arrays, which store sub-properties of a key under that same
key with a literal trailing dot appended (e.g. `dataProcessing.`
for the contents of a `dataProcessing { ... }` block) — such a
key is looked up as-is and is not itself treated as a path.

## Payload resolution {#developer-corner-data-sources-payload}

The `dataSource` option (or a processor-specific option name such
as `iterable`) is resolved as follows:

-   A **single reference** is resolved and used as-is, whatever its type — it
    is not coerced into an array.
-   **Multiple references**, configured as a TypoScript array with numeric
    keys, are resolved in ascending key order. If every reference resolves to
    an array, they are merged, with later references overriding earlier ones
    on key conflicts. If any reference does not resolve to an array, the last
    resolved reference wins outright — all earlier references, including any
    that were arrays, are discarded rather than partially merged.
-   `current = 1` bypasses the resolution entirely and uses the
    content object's current value
    (`ContentObjectRenderer::getCurrentVal()`).

A warning is logged, and the payload cannot be resolved, if the option is
empty, references an unsupported data source identifier, a data source that
is missing in the current context, or a sub-path that does not exist within
a data source. An *unconfigured* option is not an error, though — in this case,
the inline `data` fallback applies.

The `data` fallback always uses the fixed key `data`
(`data.` for an inline array in `processorConfiguration`,
or a plain `data` key already present in `processedData`),
regardless of what the primary option is called for a given processor. See
each processor's documentation for further, processor-specific fallbacks.

In PHP, the same resolution is available via
`DataSourceProvider::provide()`, see
[Resolving a data payload via a configurable keyword](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:developer-corner-data-source-aware-processor-keyword@main).