O’Reilly Report: Decoupled Applications and Composable Web Architectures - Download Now

Empower your teams & get a 582% ROI: See Storyblok's CMS in action

Skip to main content

Datasources

A data source is a collection of key-value pairs. A collection like this can define the strict options in your application/website or it can be used to define the buttons/labels in your application, that is not context-specific. You can access datasources directly through the Delivery API or use them in the Storyblok UI as the source of data in the single-option or multi-options field.

An example of datasource

An example of datasource

A good sample from the world of tech writers is the type of article. You can define multiple types (“review”, “first try”, “tutorial”, … ) as datasource values and then use them to define your articles. Similar to tags.

NOTE:

Learn more about the single-option and multi-options fields.

The structure of datasource and datasource entry

Each datasource consists of one or more datasource entries and it is represented as a single JSON file. The datasource entry object consists of the following properties.

PropertyDescription
idUnique identifier in the context of datasource.
nameThe key of the datasource key/value pair.
valueThe value of the datasource key/value pair.
dimension_valueThe given value in the requested dimension.

Datasource is defined by the following properties.

PropertyDecription
nameName of the dimension used in Storyblok UI.
id/slugIdentifier used to access the datasource content with Delivery API.
dimensionsDefinition of dimension used in datasource entries.
IMPORTANT:

To learn more about datasource objects, datasource entry objects, and how to request them, you should check the Delivery API documentation.

Datasource dimensions - internalisation

Each datasource may contain multiple dimensions. This dimension can be used to translate the values from key-values pairs. In general, the dimension can be used also for different purposes as defining different values for different situations.

You can define the dimension in the Settings of the datasource by defining its name and identifier. The name will be used in Storyblok UI and an identifier is used in the API request to get the dimension value.

Settings of datasources and dimensions

Settings of datasources and dimensions

To preview and edit the values in one of the dimensions, you need to enter the UI of the datasources. Click on the label with the name of the dimension under the search and you will see a new field under each default value of the datasource entry.

screenshot of datasource with active dimension

screenshot of datasource with active dimension

Datasource entry actions

By default, the datasource entries are saved automatically. If you want to change this behaviour, uncheck the Autosave option in the header of the datasource detail. Additional actions of the datasource entry can be found on the right-hand side of the datasource entry fields.

IconDesription
ArrowDrag & Drop the datasource entry to reorder the entries. The same order will be send by the API and shown in Storyblok UI.
Floppy DiskSaves the changes.
TrashRemoves the datasource entry.
DotRepresent the state of the datasource entry. - Green - entry is saved - Gray - entry has unsaved changes

Import and export of the datasource

Datasource entries can be imported to and exported from Storyblok as the CSV file type. You can find this functionality in the Settings of the datasource. You may export/import the datasource entries per dimension.

Datasource in the Stories

One of the main use cases for datasources is to use them as the source in the Single-Option field or the Multi-Options field. This way you may use the same group of data in multiple places through your application/website. It is a highly recommended development strategy as it creates a single source of truth for your data, which allows you to edit data only in one place in future instead of updating all occurrences of those data.

You can set the datasource as a source of the Single-Option field or Multi-Options field by selecting the Datasource option in the source dropdown and choosing one of the internal datasources. See the example of the following image.

how to select datasource as source for single-options field type

how to select datasource as source for single-options field type

How to request datasource entries with Delivery API

Datasource entries can be requested from the Delivery API using the URL like this https://api.storyblok.com/v1/cdn/datasource_entries?datasource=:slug&token=:token

Sample response from a request can be found here.

        
      // 20200626123726
// https://api.storyblok.com/v1/cdn/datasource_entries?datasource=labels&token=ask9soUkv02QqbZgmZdeDAtt

{
  "datasource_entries": [
    {
      "id": 22237,
      "name": "cancel",
      "value": "Abbrechen",
      "dimension_value": null
    },
    {
      "id": 22238,
      "name": "read_more",
      "value": "Mehr erfahren",
      "dimension_value": null
    },
    {
      "id": 37116,
      "name": "hello_email",
      "value": "hello@storyblok.com",
      "dimension_value": null
    }
  ]
}
    
IMPORTANT:

You can create and manage the datasources through our Management API. Check the datasources chapter and datasource entries chapter there.