Namespace presets¶
Some things a game needs are a list of records, not a bespoke admin page: announcements, news, rotating offers, a ban list. This page is the preset for the first of those — a ready-made schema, table layout and example document for announcements — and the shape to copy if you build another.
A list of records is a Config namespace, and the namespace editor already edits an array of records as a
table (Edit tables of game data): add and delete rows, a typed cell per column,
validation against the schema. Everything a namespace has then applies: a draft separate from what is
live, versions, publish, promote to live, roll back, and an audit row for each. Publishing an
announcement is a release, so it rolls back with the release it shipped in, and it cannot be edited
in place while players are reading it.
The admin website's Announcements page (under Content) is a friendlier way to write the same rows. It edits this namespace's draft and nothing else, so everything above still applies: it saves the draft, cuts a version and hands you to the release composer. It adds a preview of what a player would see at a time you pick, and shows the time zone you typed alongside the UTC time that is saved. The namespace and its schema below are what it needs to exist; you can still edit the same rows in the namespace editor.
You need admin to create the namespace and set its schema and presentation, and live_ops to write announcements and publish.
What you end up with¶
- a namespace named
announcements, whose document is{ "announcements": [ … ] }; - a table with one row per announcement per language, so the same news can exist in
enandja; - a
publishedflag and an optional start and end, so a row can sit in the document and out of the feed until its time comes, and stop being shown when it is over; - an
ordercolumn, so the feed has a deliberate order rather than the order rows were typed.
Step 1: Create the namespace¶
Namespaces → New namespace, name it announcements, audience client (players' games read it).
A deployment that ran config seed already has it, with this schema and an empty list (seeding
skips a namespace that exists, so nothing here overwrites your work). Config also refuses a save
or a version whose rows break a rule a schema cannot express: an ends_at that is not after its
starts_at, or two rows with the same id and locale. That is 422 validation_failed, with
each broken row listed under error.details.errors.
Step 2: Paste the schema¶
Open the namespace's Schema page, choose Edit, and paste this. It is the same JSON as
announcementsSchema in services/adminui/src/config/presets/announcements.ts, which is the copy the
console's tests validate; keep the two in step if you change either.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Announcements",
"type": "object",
"additionalProperties": false,
"required": ["announcements"],
"properties": {
"announcements": {
"type": "array",
"title": "Announcements",
"description": "One record per language. Two rows that share an id are the same announcement in two languages, so a player reads it in theirs.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["id", "locale", "title", "body", "published", "order"],
"properties": {
"id": {
"type": "string",
"title": "Id",
"pattern": "^[a-z0-9][a-z0-9-]{0,47}$",
"description": "Groups the translations of one announcement. Lower case letters, digits and dashes, and never changed once players have seen it."
},
"locale": {
"type": "string",
"title": "Locale",
"pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$",
"description": "A BCP-47 language tag, lower case: en, ja, pt-BR."
},
"title": { "type": "string", "title": "Title", "minLength": 1, "maxLength": 120 },
"body": { "type": "string", "title": "Body", "minLength": 1, "maxLength": 2000 },
"published": {
"type": "boolean",
"title": "Published",
"default": false,
"description": "A published row is one a player may be shown. Leaving it false keeps the row in the document and out of the feed."
},
"starts_at": {
"type": ["string", "null"],
"title": "Starts",
"format": "date-time",
"default": null,
"description": "When it may first be shown, RFC 3339. Null means it has no start."
},
"ends_at": {
"type": ["string", "null"],
"title": "Ends",
"format": "date-time",
"default": null,
"description": "When it stops being shown, RFC 3339. Null means it never expires."
},
"order": {
"type": "integer",
"title": "Order",
"minimum": 0,
"maximum": 9999,
"default": 100,
"description": "Lower sorts first. Two rows with the same order keep document order."
}
}
}
}
}
}
additionalProperties: false at both levels is deliberate: a typo in a column name is refused when
you save, rather than being stored and quietly ignored by whatever reads the feed.
Step 3: Say how the table looks¶
The editor works without this step, in schema property order with property names as labels. To get the
columns you want, in the order you want, add an entry to the reserved ui.presentation namespace's
document, keyed by the namespace name:
{
"announcements": {
"title": "Announcements",
"tables": {
"/announcements": {
"label": "title",
"columns": ["id", "locale", "title", "published", "starts_at", "ends_at", "order"],
"search": ["id", "title", "body"],
"newRow": { "published": false, "order": 100 }
}
}
}
}
/announcements is the JSON Pointer of the array. A column this names that the schema does not define
is ignored, and a property it does not name stays reachable from the column chooser, so this can never
hide a field for good. Publish ui.presentation the same way as any other namespace.
Step 4: Write the first announcements¶
Open the namespace. Each row is one language of one announcement. To start from a working document,
paste the example from announcementsExample in the same TypeScript file:
{
"announcements": [
{
"id": "season-rollover",
"locale": "en",
"title": "A new season starts on Friday",
"body": "Progress is kept, the ladder is reset, and the new maps are in the rotation.",
"published": true,
"starts_at": "2026-11-06T10:00:00Z",
"ends_at": null,
"order": 10
},
{
"id": "season-rollover",
"locale": "ja",
"title": "金曜日から新しいシーズンが始まります",
"body": "進行状況は引き継がれ、ランキングはリセットされます。",
"published": true,
"starts_at": "2026-11-06T10:00:00Z",
"ends_at": null,
"order": 10
},
{
"id": "store-page-refresh",
"locale": "en",
"title": "Our store page looks different",
"body": "Same game, easier to find. Nothing to download.",
"published": false,
"starts_at": null,
"ends_at": null,
"order": 20
}
]
}
The two season-rollover rows are the same announcement in two languages: they share an id and an
order, and a game that reads the namespace picks the row for the player's locale. The third row is a
draft — it is in the document, and a game that filters on published will not show it.
Step 5: Publish¶
Save draft, then Create version, then publish it as a release — Releases → Compose release,
choose the channel and the announcements version, publish. That is the same path as every other
namespace, which is the point: the announcement and the content it belongs with ship together and roll
back together.
Editing an announcement later is a new draft and a new version. A release that has already gone out is never rewritten.
What your game does with it¶
The game reads the namespace from the channel's bundle (see Content and patching) and keeps the rows where:
publishedistrue;starts_atis null or in the past;ends_atis null or in the future;localematches the player's, falling back to one you choose;
sorted by order, then by starts_at.
Making another preset¶
Any list works the same way: name the namespace, put the array under a property, describe the rows in
the schema, add a tables entry keyed by the array's pointer, and publish. Keep the schema in a module
under services/adminui/src/config/presets/ with a spec next to it, so a preset that stops validating
its own example fails a test rather than a person's afternoon.