Theme variables and data schemas

A theme carries two resources every graphic in it can use. A theme variable holds one value an operator sets per competition, such as a colour or a sponsor name. A data source template names a data schema, such as a ladder, that an operator pushes rows into per competition.

All routes sit under /rest/v2/themes/{themeId}. Write routes need themes:write. Read routes need themes:read. A theme another organization owns answers 404, the same answer as a theme that does not exist.

Theme variables

Terminal

V="themes/$THEME_ID/variables"
api GET "$V"
api POST "$V" --data '{"name":"accent","type":"string","defaultValue":"#0055ff","isStyle":true}'
api POST "$V" --data '{"name":"stage","type":"enum","enumOptions":["GROUP","FINAL"],"defaultValue":"GROUP"}'
api PATCH "$V/stage" --data '{"defaultValue":"FINAL"}'
api DELETE "$V/stage"

Types are string, number, boolean and enum. An enum variable must list at least one option in enumOptions, and its default must be one of those options. A number default must parse as a number. A boolean default must be "true" or "false".

The id takes the value of the name, so PATCH and DELETE address the variable by its name. The name never changes. To rename a variable, delete it and create it again. Set isStyle for a colour, a font or another style value; the dashboard groups style variables together.

GET answers { "updatedAt": "...", "variables": [...] }. updatedAt is the theme’s own updatedAt, not one variable’s. POST and PATCH answer the variable with updatedAt alongside it. DELETE answers 200 with { "updatedAt": "..." }. Send that updatedAt back as ifUnchangedSince on the next write; read Optimistic concurrency below.

A published theme version freezes the variables. Publish a new theme version to release a change to the overlays.

Data schemas

A data source template describes the rows an operator pushes. Send a CSV sample as sample, or send XLSX bytes as sampleBase64. The server parses the sample, infers the JSON schema, and stores the first rows as a preview.

Terminal

D="themes/$THEME_ID/data-source-templates"
api GET "$D"
api POST "$D" --data '{"alias":"standings","sourceType":"csv","shape":"rows","sample":"team,points\nEagles,42\nHawks,38\n"}'
api PATCH "$D/$TEMPLATE_ID" --data '{"description":"League ladder"}'
api DELETE "$D/$TEMPLATE_ID"

The alias uses lowercase letters, digits and underscores, and it starts with a letter. It is unique in the theme. Shapes are cell for one value, kv for a key and value list, and rows for a table. config carries parse options, for example {"headerRow":1,"dataStartRow":2} for a rows sheet.

Select the schema on a graphic with PUT /v2/themes/{themeId}/rive-graphics/{graphicId}/schemas/{alias}. Read Edit through REST for the graphic operations.

Delete is refused with 409 DATA_SCHEMA_IN_USE while a graphic selects the alias. The details list names each graphic. Deselect the schema on each graphic, then delete the template.

Pushing data

An operator pushes rows per competition, not per theme:

Terminal

api POST "data-sources/$COMPETITION_THEME_SETTING_ID/standings" \
  --data '{"csv":"team,points\nEagles,42\nHawks,38\n"}'

That route needs data-sources:write. Read External data sources for the push formats.

Optimistic concurrency

Send ifUnchangedSince with the updatedAt you last read. A theme or a template that changed since then answers 409 TARGET_CHANGED. Read the resource again, apply your change to the new state, and send the request again.

Command line

The graphics-cli package wraps both resources so you can script them without curl:

Terminal

npx ligr-graphic rive var list --theme $THEME_ID
npx ligr-graphic rive var add accent --type string --default '#0055ff' --style
npx ligr-graphic rive var set stage --default FINAL
npx ligr-graphic rive var rm stage

npx ligr-graphic rive data-schema list --theme $THEME_ID
npx ligr-graphic rive data-schema create standings --type csv --shape rows --sample standings.csv
npx ligr-graphic rive data-schema set $TEMPLATE_ID --description 'League ladder'
npx ligr-graphic rive data-schema rm $TEMPLATE_ID

Pass --theme <themeId>, or run the command from a project folder that holds a rive.json with a themeId. Neither group needs --graphic or takes a lock. Add --json to print the raw resource instead of a summary line.