Skip to content
Developers

Data binding

LOAD_GRAPHIC carries every surface. GRAPHIC_UPDATE carries the identity fields plus only the surfaces whose JSON changed. Merge an update over the state you hold.

Identity fields

Section titled “Identity fields”
FieldValue
graphicIdThe stable id of your graphic. Send it back in HIDDEN
showtrue while the graphic is on air. Informational. See Show and hide
sportThe sport key of the match, for example football

Surfaces

Section titled “Surfaces”
SurfaceContentKeyed by
sportDataLive match data for the sportSport-specific field names
controlVariablesThe current value of each control variable in your manifestVariable name
controlVariableData{ value, data } per control variable. data is the resolved fact, team or player object for an entity-typed variableVariable name
themeVariablesTheme variable values: colours, labels, sponsor namesVariable name
externalDataThe latest snapshot of each external data source of the themeData source alias
imagesPlayer, team and competition imagesEntity arrays, see below
userExpressionValuesThe value of each user expression in your manifest, evaluated by the overlay. See ExpressionsExpression name
assetOverridesAsset overrides such as ad images. OptionalAsset name

Read controlVariableData.<name>.data when you need the selected entity. Read controlVariables.<name> when you need only the raw value.

Images

Section titled “Images”
{
  "player": [{ "entityId": 501, "file": { "url": "https://…" } }],
  "team": [{ "entityId": 1, "file": { "url": "https://…" } }],
  "competition": [{ "entityId": 42, "file": { "url": "https://…" } }]
}

file can be null. Handle a missing image before you render one.

sportData by sport

Section titled “sportData by sport”

Pick your sport. The tabs stay on your choice across these docs.

These fields come from the LIGR football data model.

FieldMeaning
sportData['1']The home team. A team object
sportData['2']The away team. A team object
sportData.clockThe match clock, for example "43:30"
sportData.lastClockThe clock frozen at the end of the last live period
sportData.clockRunningtrue while the clock counts
sportData.periodShortNameThe current period, for example "First Half"
Team .scoreGoals scored
Team .abbreviationThe short team code, for example "MUN"
Team .logoUrlThe team logo URL
Team .kit.primaryColorThe kit primary colour, a hex string. If the team has no kit, the team primary background colour. "" if neither is set
Team .kit.secondaryColorThe kit secondary colour. If the team has no kit, the team primary text colour. "" if neither is set
Team .redCardsThe red card count
Team .squadThe player objects

sportData['1'] is always the home team and sportData['2'] is always the away team.

sportData.fixtures lists the matches of the same competition on the same calendar day. The list includes the current match. It leaves out cancelled matches and matches without team competitors. LIGR sorts the list by date, then start time, then home team name. In a Rive expression, read the list as $d.fixtures.

Fixture fieldMeaning
idThe match id
dateThe match date, for example "2026-09-29"
homeTeamName, awayTeamNameThe team names
homeTeam, awayTeamThe team branding: logoUrl, background and text colours, and kit. null if the match has no team on that side
homeGoals, awayGoalsThe goals of each team. null before kick-off
startTimeThe kick-off time in 24-hour format, for example "15:00"
isLivetrue while the match is in progress
roundThe round key of the match
currentPeriodThe current period object. null if the match has no current period

For a field not listed here, read the schema.

Schemas

Section titled “Schemas”

The overlay sends no schemas at runtime. Get each shape during development.

SurfaceWhere the schema is
sportDataGET /v2/schemas/sports/{sport}
Entities: team, player, playerPair, factGET /v2/schemas/control-variables
controlVariablesThe controlVariables of your manifest
themeVariablesThe theme variables of the theme
externalDataThe data schemas of the theme: ligr-graphic rive data-schema list

Validate your test payloads against these schemas during development. A wrong field name shows up before you ship. GET /v2/scenarios/{sport} returns sample sportData for a sport. See Schemas & scenarios.

External data

Section titled “External data”

A theme can declare external data sources: a standings table, a sponsor line, a fact file. Your graphic reads them from externalData by alias. Anyone with a write key fills them over REST. See External data sources.

A large data source is the usual cause of a message over the 1 MB limit. Keep the snapshot to what the graphic renders.