JSON Data Source

8 min

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

{
    "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:

{
    "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 Overviewdata

Advanced Features

Dynamic URL from context

The url value supports $context interpolation:

{
    "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.

Data Sources Overview

Context Data Sourceco

Custom Data Sourcecus