Data Sources

12 min

Overview

A data source is the configuration that tells a list component (e.g., a list, swiper, or dropdown) where to fetch its data from and how to present it. Data Sources are defined inside component configurations in views.json and handle fetching, caching, pagination, and making data available to child components through the context system.

Every data source shares a set of common configuration properties and has a type field that determines which data it loads.

Data Source Types

Type	Description
content	Issues, bundles, and posts from the Catalog API
publication	Publications from the Catalog API
subscription	Subscription plans that are available for purchase
search-result	Full-text search results
taxonomy	Taxonomy nodes (tags, topics, etc.)
collection-content	Contents of a specific collection
collection	Collections from the Catalog API (deprecated; use collection-content)
json	Arbitrary JSON array from a URL or local resource file
custom	Statically defined list of items in views.json
context	Data already present in $context, re-exposed as a list
bookmark	User's bookmarked content
menu	Menu items from the Catalog API
period	Time periods (years/months) derived from issue publication dates
ad	Ad slots from the ad configuration
issue	Issues (deprecated, use content)
category	Categories (deprecated, use taxonomy)

Common Configuration

These properties are available on every data source type.

Property	Type	Default	Description
type	string	—	Required. Identifies which data source to use (see table above)
contextKey	string	—	Key under which loaded data is published in $context, e.g., $context.myKey gives the array of items
contextProperty	string	—	When set, only this property of each item is stored in context instead of the full object (e.g., ID to store only IDs)
limit	number	—	Maximum total number of items to load
offset	number	—	Skip the first N items
batchSize	number	24	Number of items fetched per API call (used for lazy loading / "load more")
cursor	string	—	Starting cursor, overrides the default start position
randomize	boolean	false	Randomize the order of loaded items
maxCacheAge	number	global default	Cache TTL override in milliseconds
preventSSRCache	boolean	false	Forces the client to re-fetch data even when SSR-cached data is available (use for user-specific data like entitlements)
ad	object	—	Insert ads between items — see Ad InsertionAd Insertion
loadAll	boolean	false	(Deprecated) Keeps loading until no next page exists

All numeric properties (limit, offset, batchSize, maxCacheAge) also accept a string (parsed as an integer) or a conditional value

Conditional Values

Any property that accepts a conditional value can be written in one of three forms:

// Plain value
"limit": 10

// Conditional — use 10 if condition is true, otherwise no limit
"limit": {
  "value": 10,
  "condition": { "value": "$context.someFlag", "operation": "SET" }
}

// Conditional with fallback — use 10 if true, 5 otherwise
"limit": {
  "value": 10,
  "condition": { "value": "$context.someFlag", "operation": "SET" },
  "fallback": 5
}

// Conditional web, 10 on all other platforms
"limit": {
  "value": 20,
  "condition": {  "operation":"EQUALS", "compareValue": "WEB" },
  "fallback": 10
}

When the condition is not met and no fallback is provided, the property behaves as if it was not set.

Conditions

A condition object controls whether a filter clause or conditional value is active at runtime. Conditions are evaluated against the current context . See Context Updatescontext updates

Condition properties

Property	Type	Description
value	string	The value to evaluate. Supports $context, $global, $functions -see (Value interpolationValue interpolation)
operation	string	Comparison operation (see table below). Default: EQUALS
compareValue	string	The reference value to compare against
negated	boolean	Invert the result of the condition
stringIgnoreCase	boolean	Use case-insensitive string comparison
AND	condition[]	All conditions must be true
OR	condition[]	At least one condition must be true

Operations

Operation	Description
EQUALS	value == compareValue (default)
EQUALS_NOT	value != compareValue
SET	value is not null/empty
NOT_SET	value is null or empty
EMPTY	value is an empty array or string
NOT_EMPTY	value is a non-empty array or string
CONTAINS	value (string or array) contains compareValue
LESS_THAN	parseInt(value) < parseInt(compareValue)
GREATER_THAN	parseInt(value) > parseInt(compareValue)

Example

{
  "condition": {
    "AND": [
      { "value": "$context.publication.id", "operation": "SET" },
      { "value": "$context.platform", "operation": "EQUALS_NOT", "compareValue": "WEB" }
    ]
  }
}

Value Interpolation

String values inside filters and conditions are dynamically resolved at runtime. Three scopes are available:

Identifier	Access pattern	Description
$context	$context.publication.id	Current view context — publication, issue, category, search result, platform, etc.
$global	$global.experienceConfig.myKey	Globally loaded data available across all views (see: Global Data)
$functions	$functions.myFn(arg1, arg2)	Custom JavaScript functions registered in custom.server.js

Dot notation and bracket notation are both supported: $context.issue.title, $context['search-result'].excerpt. When a $context or $global path resolves to null or undefined, any URL segment containing that value is automatically removed from the resulting string.

Filter Path-Param Interpolation

Filter values that start with : are automatically replaced with the matching URL path parameter. For example, a filter value of :publicationId resolves to the publicationId segment of the current URL at runtime. This allows a single view definition to serve filtered content for any publication without additional custom logic.

Filter Logic (AND/OR)

All filter types support AND and OR arrays for combining multiple filter clauses. Each clause can carry its own condition so individual clauses can be toggled at runtime:

"filter": {
  "OR": [
    {
      "id": { "value": "pub-123" }
    },
    {
      "id": { "value": "pub-456" },
      "condition": { "value": "$context.platform", "operation": "EQUALS", "compareValue": "WEB" }
    }
  ]
}

A filter clause whose condition evaluates to false is silently dropped. If all clauses are dropped, the filter is treated as absent.

When a filter value is an array, it is automatically expanded into an OR across all values, so "value": ["a", "b"] is equivalent to OR: [{ value: "a" }, { value: "b" }].

Ad Insertion

A data source can interleave ad slots into its item list using the ad property:

"ad": {
  "adId": "banner-ad",
  "interval": 3,
  "after": 1,
  "indexed": true,
  "startIndex": 0
}

Property	Description
adId	ID of the ad definition from ads.json
interval	One ad is inserted for every N regular items
after	First ad appears after this many items (defaults to interval)
indexed	Append a numeric suffix to adId for each ad slot (e.g., banner-ad0, banner-ad1)
startIndex	Starting index for the suffix when indexed is true (default: 0)

The ad property also accepts a condition value to enable or disable ad insertion at runtime.