Skip to content

Structured Data

Structured data lets you store information that isn’t an article in the News Suite: sports fixtures and teams, products, venues, election results, and so on. You decide the shape of the data yourself, as a collection with typed fields. Records are the entries in a collection.

Records are usually filled by a connector, a script or service that writes them through the API from an external source such as a sports data provider. Editors can also add and edit records in the CMS, link them to articles, and frontends read them through the API.

This guide covers:


Use… When the information… Examples
A content type (Content Types) Is written by people, and published as a story with a title, category and date Match reports, previews, reviews
A structured data collection Comes from a feed or a database, changes often, or has no category or publish date Fixtures and live scores, teams and players, products, venues

The two work together: an article can point to records. For example, a Match report content type can have a field that picks the match it’s about. The frontend then shows the live score from the match record next to the editor’s text.


  1. In the CMS sidebar, open Publisher Configuration under the Administration section.
  2. In the right-hand rail, click Structured data (the database icon).
  3. Click Create collection.
  4. Fill in the details:
    • Name: The collection’s name, e.g. Matches.
    • Key: The collection’s name in the API, e.g. matches for /cms/data/matches/records. Use lowercase letters, numbers and underscores. The key can’t change once the collection is created.
    • Description: Optional. Shown in the collections list.
    • Icon: Optional. Shown in the collections list.
  5. Add the collection’s fields (see Fields).
  6. Under API, set:
    • Status of new records: The status a record gets when a connector doesn’t send one. Frontends only see Published records.
    • Cache time: How long frontends and the CDN may keep published records, in seconds (default 60). Use a few seconds for live data, such as scores, or 0 for no caching.
  7. Click Create collection.

Once the collection is saved, you can also choose its Title field: the text field that names each record in lists, pickers and the API’s title. By default it’s the first text field.

The collections list shows each collection’s key, number of fields and records, and last change. Its … menu has Records, Copy key, Copy API path and Delete.


Click Add field in the collection’s Fields section. In the field window:

  • Name: The field’s name in the CMS, e.g. Kick-off.
  • Key: The field’s name in the API, e.g. kickoff. It’s suggested from the name; change it before saving if you want. Use lowercase letters, numbers and underscores.
  • Type: See the table below.
  • Description: Optional help for connector developers, shown in the collection’s schema.
  • The options for the type, then Several values (a list), Required, Filterable and sortable in the API and Unique, where the type allows them.
Type Holds Options Several values Filterable
Text A single line of text Maximum length Yes When ticked
Long text / HTML Longer text or HTML No No
Number A number Range (minimum, maximum), whole numbers only Yes When ticked
Yes / no True or false No When ticked
Date A date Yes When ticked
Date and time A date and time, with its time zone Yes When ticked
Predefined list One of a list of values Values, one per line Yes Always
Map (coordinates) A latitude and longitude No No
Media A media attachment Yes Always
Reference Another record, an article, an author or a category Points to Yes Always
JSON Any JSON object or list No No
  • Required: Every record must have a value.
  • Filterable and sortable in the API: The field can be used to filter and sort records, in the API and in the CMS’s filters. Lists, references and media are always filterable.
  • Unique: No two records can hold the same value, e.g. a team’s code.
  • Reference › Points to: Another collection’s records (Teams (records)), Content, Author or Category. A collection can point to itself once it’s saved.

Drag the rows to change the fields’ order. The order is the record form’s order.

  • A field’s key and type can’t change once saved. Records and connectors depend on them. To change one, add a new field instead.
  • Removing a field keeps its data in the records, but the API stops reading and writing it. If you add a field with the same key and type again later, its data comes back.
  • Making a field filterable indexes the existing records in the background. Filters on that field are complete once the background job finishes.

To see a collection’s records, click Records on the collection’s page, or the record count in the collections list.

The records list shows each record’s title, external id, up to three of its fields, its status and its last change.

  • Filters: Click Filters to search titles, filter by status, and filter by the collection’s filterable fields: text that contains a word, numbers from–to, dates with the date range picker, yes/no, list values and references.
  • Sorting: Click the Title or Last change header.
  • Load more: The list shows 50 records at a time.

Click Add record, or a record’s title, to open the record form. The form is built from the collection’s fields:

  • Text, long text and numbers are typed in.
  • Yes / no is a switch.
  • Dates and date-times use date pickers. Date-times are entered in the site’s time zone.
  • Predefined lists are a dropdown.
  • Map fields use the map picker: click the map, drag the marker, or type the coordinates.
  • References use a search dropdown.
  • JSON is typed as text.
  • A field with several values takes one value per line, or several picks in its dropdown.

The form also has the record’s Status and External id: the connector’s own id for the record, unique in the collection.

Click Save changes. If something isn’t valid, each problem shows under its field and in a list at the top of the form. The record form uses the same rules as the API.

Use Delete record in the record’s … menu, or Delete in the records list. If other records point to it, for example matches pointing to a team, the warning says how many. Those records keep a reference to nothing.


To let editors pick records in articles, add a Structured data record field to a content type:

  1. Open the content type in Publisher Configuration › Content Types (Content Types).
  2. Click Add field and choose Structured data record under From Database.
  3. Give it a Field Name and System-level code, e.g. Match and match.
  4. Choose the Collection it picks from.
  5. Tick Allow adding multiple values if an article can link several records, e.g. Teams.
  6. Save the field, then the content type.

In the content editor, the field appears under Classification in the article’s details:

  • Search in the dropdown by title, or by a record’s id or external id. Drafts are marked (draft).
  • Click Choose… to browse the collection’s records in a window, with the same filters as the records list. Tick a record (or several, for a field with several values) and click Continue. Each row’s … menu has Open in new tab, which opens the record without leaving the article.

An article’s record field comes back as the record itself, in the same shape as /cms/data, not just its id. A field with several values comes back as a list.

  • Only published records are included.
  • The record is always current, even when the article itself is cached. A live score updated by the connector shows on the next request.

Structured data has its own permission group, Structured data, in the role editor (Users, Roles, and Permissions):

Permission Allows
Structured data - List collections Opening Structured data
Structured data - View collection Opening a collection
Structured data - Create collection Creating collections
Structured data - Update collection Changing a collection’s fields and settings
Structured data - Delete collection Deleting collections
Structured data - List records Opening a collection’s records
Structured data - View record / Create record Opening the record form
Structured data - Write records Saving, adding and deleting records, in the CMS and through the API

Granting the whole group’s read or write access covers these permissions.

Editors don’t need any of these permissions to pick records in the content editor: the search dropdown and Choose… work for anyone who can edit the article. Open in new tab needs View record.

API keys. Reading published records works with any API key. Writing records or collections, or reading drafts, needs an API key linked to a CMS user whose role has the matching permissions. Without them, the API answers 403 and names the missing permission.


Records can start automations (Setting up automations), for example to tell a frontend or another system that data changed through Send webhook. Under Structured data, the triggers are:

  • Structured data record created
  • Structured data record updated
  • Structured data record published: A record became published, including one created as published.
  • Structured data record deleted

A write that changes nothing (the same data sent again) starts no automation.

To react to one collection only, add Add step › Conditions › Trigger… › Collection key, e.g. Collection key equals matches.

A webhook’s payload holds the record in its parameters: record_id, collection (the key), external_id, status and user_id.


Use Delete in the collections list, or Delete collection in the collection’s … menu.

  • A collection that other collections’ reference fields point to can’t be deleted. Remove those fields first.
  • A collection with records is deleted with its records, in the background. The warning says how many records will be deleted. It can’t be undone.

This section is for developers who build connectors, which write records, or frontends, which read them. The API reference has every endpoint and field under Structured data.

All endpoints are under the CMS API base, e.g. https://cms.example.com/cms, and need the API-Key header. Writing needs an API key linked to a CMS user (see Permissions).

Endpoint Use it for
GET /cms/data Listing collections and their fields
GET /cms/data/{collection} A collection’s fields and the JSON Schema of a record’s data, to check what you send
POST /cms/data, PUT /cms/data/{collection}, DELETE /cms/data/{collection} Creating, changing and deleting collections from a connector
PUT /cms/data/{collection}/records/external/{externalId} Creating or replacing a record by your own id. The main call for connectors
POST /cms/data/{collection}/records/bulk Creating or replacing up to 500 records at once
POST /cms/data/{collection}/records Creating a record
PATCH /cms/data/{collection}/records/{id} Changing part of a record
DELETE /cms/data/{collection}/records/{id} Deleting a record
GET /cms/data/{collection}/records Listing records, with filters, sorting and include
GET /cms/data/{collection}/records/{id}, GET …/records/external/{externalId} One record
GET /cms/data/{collection}/records/{id}/referenced-by The records pointing to a record, e.g. a team’s matches

Use the upsert call with your source’s own id. Sending the same data again changes nothing and answers "result": "unchanged", so connectors can safely send everything on every run.

PUT /cms/data/matches/records/external/opta:m1
API-Key: …
Content-Type: application/json
{
"status": "published",
"data": {
"label": "Arsenal v Chelsea",
"home": { "externalId": "opta:t3" },
"away": { "externalId": "opta:t8" },
"kickoff": "2026-11-20T20:00:00Z"
}
}
  • References can be a record’s id, or { "externalId": "…" } in the target collection. Add ?createMissingRefs=1 to create a draft placeholder for a reference that doesn’t exist yet, e.g. a team the connector hasn’t sent.
  • Errors answer 400, with the message per field: { "error": "The record is not valid.", "errors": { "kickoff": "Must be a date and time in ISO 8601…" } }.
  • Bulk writes answer 207 when some records failed. Each item in results says what happened to it. A record can point to one earlier in the same batch.
  • Dates and times are ISO 8601. A date-time without a time zone is taken as UTC.
GET /cms/data/matches/records?filter[kickoff][gte]=2026-11-25&sort=kickoff&include=home.country,away
  • Filters work on filterable fields: filter[field]=value (comma-separated: any of them), or filter[field][op]=value with eq, neq, gt, gte, lt, lte, between (from,to), exists (1 or 0) and like (contains, for text and lists). You can also filter on id, externalId, createdAt, updatedAt and publishedAt.
  • q searches titles. sort takes up to three fields, with - for descending (default -updatedAt). page_number and limit (up to 100) page the results.
  • include expands reference fields with what they point to, up to two levels (home.country). Expanded records are in each record’s included.
  • Frontends only get published records. API keys linked to a CMS user who can read Structured data can ask for drafts with status=draft,published.
  • Caching: published responses are cached for the collection’s Cache time. Every write in the collection refreshes its lists straight away, so don’t add longer caches of your own.
Limit
Fields per collection 100
Records per bulk request 500
Records per page 100
Filters per request 10
include depth 2 levels
External id 191 characters
Values in a field with several values 1,000

With structured data, you can bring data from feeds and databases into the News Suite, keep it up to date automatically, and let editors link it to their stories. If you encounter any issues or need further assistance, please reach out to the support team.