---
title: JSON Data Source
slug: experience/json-data-source
docTags: 
createdAt: 2026-05-12T15:35:55.398Z
---

## Overview

The `json` data source fetches an arbitrary JSON array from a remote URL or a local resource file bundled with the app. It is the escape hatch for data that does not come from the Catalog API — external feeds, third-party services, or static JSON files shipped with the app.

## When to use this

Use `json` when your data lives outside the Catalog API: an external REST endpoint that returns a JSON array, or a static JSON file in the app's resource bundle. If the data comes from the Catalog API, use a more specific type like `content` or `taxonomy` instead.

## Basic Example

```json
{
    "type": "json",
    "contextKey": "menuLinks",
    "url": "https://example.com/api/navigation.json"
}
```

This fetches the JSON array from the given URL and exposes it as `$context.menuLinks`. Each element of the array becomes an item available to child components.

## Configuration

### Type-specific properties

| Property | Type   | Default | Description                                                                            |
| -------- | ------ | ------- | -------------------------------------------------------------------------------------- |
| url      | string | —       | **Required.** URL of the remote JSON endpoint, or a `resource://` path for local files |
| headers  | object | —       | HTTP headers to include in the request (e.g. for authentication)                       |

### Using a local resource file

To load a JSON file bundled with the app instead of a remote URL, use the `resource://` scheme:

```json
{
    "type": "json",
    "contextKey": "config",
    "url": "resource://data/config.json"
}
```

The file must be placed in the app's resource directory at the corresponding path.

### Common configuration (inherited)

All common data source properties apply — `limit`, `offset`, `batchSize`, `contextKey`, `maxCacheAge`, `preventSSRCache`, etc.

For more details, see: [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)

## Advanced Features

### Dynamic URL from context

The `url` value supports `$context` interpolation:

```json
{
    "type": "json",
    "contextKey": "feed",
    "url": "https://example.com/api/feed/$context.publication.id.json"
}
```

If the interpolated segment resolves to `null` or `undefined`, that URL segment is automatically removed from the resulting string.

For more details on value interpolation, see:
[TODO insert link to Value Interpolation](#)

## Testing Notes / Edge Cases

- **Response must be a JSON array**: The endpoint must return a top-level JSON array `[...]`. A JSON object `{...}` at the root will fail — wrap it or use a different approach.
- **CORS**: Remote URLs must allow cross-origin requests from the app's domain. A blocked CORS request silently returns an empty list on the client.
- **SSR vs. client fetch**: On SSR, the URL is fetched server-side (no CORS issue). On the client, CORS applies. Set `preventSSRCache: true` if the data changes frequently or is user-specific.
- `maxCacheAge`: Remote JSON is cached. Set `maxCacheAge` appropriately for how frequently the external data changes.
- **Authentication**: If the endpoint requires auth headers, use the `headers` property. Do not embed tokens directly in the URL.
- **Local resource files**: The file path is relative to the app's resource root. A missing file returns an empty list with no visible error in the UI.

## Related Topics

- [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)
- [Context Data Source](docId\:gfxLBZbyRNYfolnqHwiXi)
- [Custom Data Source](docId\:Fownkj3bWKtRlGn6mGudn)