JSON

The JSON datasource allows you to display data from a JSON source in Smartsign.

This makes it possible to integrate data from external systems, APIs, or internally published JSON files into your digital signage content.

JSON (JavaScript Object Notation) is a structured data format commonly used by modern APIs and web services. It represents data using objects and arrays, making it easy to extract individual values and display them on screens.

info

This datasource is intended for users with basic technical knowledge of JSON and JSONPath. While powerful, it may be more complex to configure compared to other datasources.

How it works

When connected, Smartsign retrieves JSON data from the specified source URL and makes it available in the Template Creator using JSONPath expressions.

The JSON data can be fetched either:

• Via the Smartsign server (default, cached for performance and security).
• Or directly from the source by the screen or browser, depending on configuration.

The retrieved data can then be databound to text or image elements in a template.

Requirements

To use the JSON datasource, you need:

• An accessible JSON source available over HTTP or HTTPS.
• The JSON source must be encoded in UTF-8
• Basic technical knowledge of JSON and JSONPath.

If you plan to use direct requests, the JSON source must also comply with standard browser security rules (CORS).

Set up the datasource

The first step is to configure your data source with the JSON source you want to use.

In this example we will use a basic URL without any request headers or requirements, but you can read more about them in the configuration details below.

The URL should look like something like this: https://server.example.com/data.json

• Go to Template datasources and select create new datasource.
• Select the JSON datasource.
• Configure the datasource by adding Name, Description and JSON Link.
• Click Create and verify data connection to see if data can be fetched.
• Once created, you can confirm that data has been fetched.

Datasource is now ready to be used.

Example JSON data

Once the datasource is configured and data can be fetched, it becomes easier to inspect the JSON structure and identify the fields you want to display.

The example below represents a real estate property listing returned from a JSON-based API.

In this case, the following values can be displayed in a template:

• Street address
• Property type
• Price
• Description
• Images

{
  "ads": [
    {
      "estate": {
        "price": "€ 989,000",
        "street": "176 Hillview Sidings St.",
        "town": "Port Vermo, WA3259",
        "description": "Rare opportunity available in the heart of Port Vermo.",
        "property-type": "Single family residence"
      },
      "images": [
        {
          "url": "https://server.example.com/image.jpg"
        }
      ]
    }
  ]
}

Identifying JSONPath expressions

JSONPath is used to tell Smartsign where in a JSON structure a specific value is located. It defines the path from the root of the JSON document to the element you want to display.

JSONPath expressions are case-sensitive and must match property names exactly as they appear in the JSON.

Paths use dot notation, for example: $.ads[0].estate.street

JSONPath notation

Expression	Description
$	The root object or array.
.property	Selects the specified property in a parent object.
[n]	Selects the n:th element from an array. Indexes are 0-based.

Using the example JSON above, the following JSONPath expressions can be used to bind data fields in a template.

JSONPath examples

Field	JSONPath	Result
Street address	$.ads[0].estate.street	176 Hillview Sidings St.
Price	$.ads[0].estate.price	€ 989,000
Property type	$.ads[0].estate.property-type	Single family residence
Description	$.ads[0].estate.description	Property description text
Image	$.ads[0].images[0].url	Image URL

Iterators

When working with lists or arrays in JSON, an index (such as [0]) can be replaced with an iterator expression.

Using an iterator causes the index to start at 0 and automatically increment at a defined interval, allowing multiple items to be shown one at a time.

Example

$.ads[(iterator(20))].estate.price

This means:

• The index starts at 0.
• The displayed item changes every 20 seconds.
• All JSONPath expressions must use the same iterator value to stay synchronized.

To select a specific item instead, use a fixed index:
$.ads[0].estate.price

Create a JSON template

Once the datasource is configured, you can create a JSON template to display the data.

A JSON template can either be created from scratch, or you can download a suitable template from the Marketplace and adapt it to your needs. If you are new to templates, please see the Template Creator guide to learn the basics.

• Create, edit or download templates from the Templates menu.

• Open the template and add text fields and image placeholders for the JSONPath data.

• Bind each element to its corresponding JSONPath expression. The Select JSONPath from test data option helps you identify the correct property when binding fields.

  • Street Address $.ads[(iterator(20))].estate.street
  • Property type .$.ads[(iterator(20))].estate.property-type
  • Description $.ads[(iterator(20))].estate.description
  • Price $.ads[(iterator(20))].estate.price
  • Image $.ads[(iterator(20))].images[(iterator(20))].url

• Save the template and it can now be used to create a Smart Media to publish on screens.

Technical information

JSON source must be encoded in UTF-8.

Datasource configuration options

Setting	Description	Example
JSON Link	The complete URL to the JSON file including protocol	https://server.example.com/data.json
HTTP method	Select which HTTP method to use when fetching the JSON data. GET is typically used for static URLs or APIs without a request body. POST can be used for APIs that require parameters or payloads in the request body.	GET
Fetch test data	Fetches data to Template Creator from the configured link. The link text will light up green on success. Fetching data makes it possible to select JSONPaths from the data when creating bindings.
Data Update Time	Time in seconds between updates Restrictions (regardless of set value) Server requests: 5 minutes Direct requests: 2 seconds	3600
Special request headers	HTTP header key and value pairs	Key = Authorization Value = Bearer XyzXyzXyzXyz
Use direct requests	Enable to request data direct from source instead of proxying through Smartsign Server Server fetched data is cached by the server for 10 minutes for load balancing and security. Direct fetched data is subject to browser security rules https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS	False
Data transformation script	Careful! Programming knowledge required. It's possible to transform/manipulate the data before showing it by providing a script here. The JSON data is available in the variable "input" Moment.js is available to work with date/time. The function must return the data when the transformation is completed.	function(input, moment, smartsign) { // do your transformation here // ex: input['myvar3'] = input['myvar1'] - input['myvar2']; return input; }

Limitations and considerations

• JSON files must be UTF-8 encoded
• JSONPath expressions are case-sensitive
• Direct requests are subject to browser CORS restrictions
• Complex transformations require JavaScript knowledge