Gaming Inventory File Schema

This page defines the customer-facing Gaming Inventory file contract for Optimove Personalize.

Root object contract

The file must be valid UTF-8 JSON containing one non-empty object:

{
  "SLOT001": {
    "game_code": "SLOT001",
    "game_name": "Adventure Quest"
  }
}

Each top-level key identifies one game. For every game:

• the top-level key must exactly equal the nested game_code;
• comparison is case-sensitive;
• game_code is a required, non-empty string; game_name is strongly recommended and, when sent, must be non-empty;
• do not use an apostrophe in a game code; the current processor normalizes apostrophes in top-level keys to hyphens;
• the same game_code must be sent as ootb_game_code in Personalize real-time events;
• unknown top-level games from the previous successful snapshot are deletion candidates when omitted; and
• JSON property order has no meaning.

An empty object can pass parts of the current API validation but is not a valid customer snapshot. Reject it locally.

Type and omission rules

Use JSON-native types. In particular:

• use true or false for new, without quotation marks;
• use 0 or 1 integers for platform flags;
• use a decimal between 0 and 1 for rtp, such as 0.96, not 96;
• use arrays where the table specifies an array, even for one value; and
• do not send numbers or Booleans as strings.

Unless a field-specific rule below says otherwise, an optional field that is omitted or set to null provides no value for that feature. Platform fields are the exception: never send them as null. Omitting useful metadata can reduce filtering, modelling or response-enrichment capabilities.

Complete field dictionary

Platform availability

Send all three platform fields explicitly on every game:

{
  "desktop": 1,
  "mobile": 1,
  "tablet": 0
}

At least one platform must be 1. If all three are omitted, processing defaults all three to 1, which can unintentionally make a game available everywhere. If some fields are present and others absent, validation and downstream behaviour are harder to reason about; explicit values avoid ambiguity.

Do not send null for any platform field. The current validator can treat three explicit nulls like omission, while processing treats the keys as present and produces no platform availability. Either omit all three fields or, preferably, send all three as explicit 0 or 1 integers.

Tags and game features

Both fields accept customer-defined keys and JSON values. Use one key/value pair per object:

{
  "game_features": [
    { "variance": "high" },
    { "free_spins": true },
    { "reels": 5 }
  ],
  "tags": [
    { "exclusive": true },
    { "seasonal": "Halloween" }
  ]
}

Do not combine several keys in one object. Current processing consumes one pair from each object, so later pairs in the same object may be ignored.

Invalid:

{
  "game_features": [
    {
      "variance": "high",
      "free_spins": true
    }
  ]
}

Also avoid empty objects such as "tags": [{}].

Availability rules

Availability fields remove ineligible games before recommendations are returned.

Use skin_id and regulation for the standard dimensions:

{
  "skin_id": ["main"],
  "regulation": ["GB", "DE"]
}

Use inclusions and exclusions for additional context dimensions:

{
  "inclusions": {
    "country": ["GB", "DE"],
    "customer_tier": ["gold", "platinum"]
  },
  "exclusions": {
    "currency": ["USD", "CAD"]
  }
}

For a given dimension, use a clear inclusion or exclusion policy. Avoid placing the same dimension/value in both objects. A rule only works when its field name and value use exactly the same vocabulary as the recommendation request context.

Complete valid example

The following one-game example demonstrates all 27 supported customer fields. In production, include every game intended to remain in the catalogue.

{
  "SLOT001": {
    "game_code": "SLOT001",
    "game_name": "Adventure Quest",
    "game_category": "Slots",
    "game_class": "Video Slots",
    "game_type": "Five Reel",
    "description": "A five-reel adventure slot with bonus rounds.",
    "desktop": 1,
    "mobile": 1,
    "tablet": 1,
    "extra_channels": "iOS|Android",
    "rtp": 0.96,
    "themes": ["Adventure", "Exploration"],
    "launch_date": "17/05/2025",
    "new": false,
    "supplier": "Example Games",
    "default_order": 10,
    "jackpot_type": "progressive",
    "formatted_summary": "Adventure Quest is a five-reel slot with an expanding map and three bonus rounds.",
    "formatted_summary_short": "A five-reel adventure with three bonus rounds.",
    "image_url": "https://cdn.example.com/games/slot001.jpg",
    "game_features": [
      { "variance": "high" },
      { "free_spins": true }
    ],
    "tags": [
      { "exclusive": false },
      { "seasonal": "Summer" }
    ],
    "skin_id": ["main", "premium"],
    "regulation": ["GB", "DE"],
    "inclusions": {
      "country": ["GB", "DE"]
    },
    "exclusions": {
      "currency": ["USD", "CAD"]
    },
    "extra": {
      "lobby_path": "/games/slot001",
      "studio": "North"
    }
  }
}

Pre-upload contract checklist

Before calling /validate, verify locally that:

• The root is a non-empty object.
• Every desired game for the brand is present.
• Every root key exactly equals game_code.
• No game_code contains an apostrophe.
• Every game has a non-empty game_code; game_name is present wherever available.
• Every game_code is unique and stable across uploads.
• game_code matches ootb_game_code in real-time events.
• Platform flags are explicit 0 or 1 values and at least one is 1.
• No platform flag is null.
• rtp values are between 0 and 1.
• launch_date values are real calendar dates in DD/MM/YYYY format.
• new values are JSON Booleans.
• Tags and features contain one key/value pair per object.
• Availability field names and values match recommendation context.
• Every removal compared with the last successful snapshot is intentional.
• A snapshot removing more than half of the current games is blocked pending coordination with Optimove.

Continue with the quickstart or review monitoring and recovery.