--- title: Data Sources slug: experience/data-sources docTags: createdAt: 2026-04-13T14:14:11.472Z --- ## 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 Insertion](docId\:fuMBUaBWeON_OTO5wfevf) | | `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: ```json // 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 Updates](docId\:jgOZe9CpyPcEj7Iz3lCux) ### Condition properties | Property | Type | Description | | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `value` | string | The value to evaluate. Supports `$context`, `$global`, `$functions` -see ([Value interpolation](docId\:fuMBUaBWeON_OTO5wfevf)) | | `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 ```json { "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](https://app.archbee.com/docs/qtjKveW7g556Yo3qfoyAY/hh7ytTOXEleThDlPM_7dl)) | | `$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: ```json "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: ```json "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. ##