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:
- Creating a collection and its fields
- Managing records in the CMS
- Linking records to content
- Permissions and automations
- Connecting data through the API, for connector and frontend developers
Structured data or a content type?
Section titled “Structured data or a content type?”| 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.
Creating a collection
Section titled “Creating a collection”- In the CMS sidebar, open Publisher Configuration under the Administration section.
- In the right-hand rail, click Structured data (the database icon).
- Click Create collection.
- Fill in the details:
- Name: The collection’s name, e.g. Matches.
- Key: The collection’s name in the API, e.g.
matchesfor/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.
- Add the collection’s fields (see Fields).
- 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.
- 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.
Fields
Section titled “Fields”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.
Field types
Section titled “Field types”| 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.
Changing fields
Section titled “Changing fields”- 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.
Managing records
Section titled “Managing records”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.
Adding and editing a record
Section titled “Adding and editing a record”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.
Deleting a record
Section titled “Deleting a record”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.
Linking records to content
Section titled “Linking records to content”To let editors pick records in articles, add a Structured data record field to a content type:
- Open the content type in Publisher Configuration › Content Types (Content Types).
- Click Add field and choose Structured data record under From Database.
- Give it a Field Name and System-level code, e.g. Match and
match. - Choose the Collection it picks from.
- Tick Allow adding multiple values if an article can link several records, e.g. Teams.
- 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.
In the content API
Section titled “In the content API”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.
Permissions
Section titled “Permissions”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.
Automations
Section titled “Automations”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.
Deleting a collection
Section titled “Deleting a collection”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.
Connecting data through the API
Section titled “Connecting data through the API”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 |
Writing records
Section titled “Writing records”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:m1API-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=1to 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
207when some records failed. Each item inresultssays 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.
Reading records
Section titled “Reading records”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), orfilter[field][op]=valuewitheq,neq,gt,gte,lt,lte,between(from,to),exists(1or0) andlike(contains, for text and lists). You can also filter onid,externalId,createdAt,updatedAtandpublishedAt. qsearches titles.sorttakes up to three fields, with-for descending (default-updatedAt).page_numberandlimit(up to 100) page the results.includeexpands reference fields with what they point to, up to two levels (home.country). Expanded records are in each record’sincluded.- 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.
Limits
Section titled “Limits”| 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 |
Conclusion
Section titled “Conclusion”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.