Versioning

Versioning#

GAME distinguishes between two types of versioning: the API schema and the individual module.

API Schema Version (game_schema_version)#

The game_schema_version tracks which version of the GAME API specification a module implements. The schema version covers the entire GAME release — the Evaluator request spec, Predictor response spec, and Matcher spec. Changes to the API specification (e.g. the addition, removal, or modification of keys) will be accompanied by a schema version increment and published release notes. The game_schema_version field is set manually by the module builder in the help file and should be updated when the module is modified to conform to a new version of the GAME API.

Compatibility policy#

The schema version follows a MAJOR.MINOR format:

  • Minor increments (e.g. 1.0 → 1.1 → 1.2): Represent the addition of optional keys that some modules may use but others can safely ignore if they don’t need those keys or values. Modules built for any version within the same major release (e.g. 1.*) are compatible with each other.

  • Major increments (e.g. 1.* → 2.0): Represent mandatory changes such as the addition, removal, or renaming of required keys. Modules built for an older major version may not be compatible and should be updated.

Where to store it#

  • Predictors: Set game_schema_version in the predictor_help_message.json. This is returned via the GET /help endpoint

  • Evaluators, Matcher, & Predictor Distributor (PD): Set game_schema_version in the %labels block of the Apptainer definition file (.def).

Predictor, Evaluator, Matcher, and PD schema versions are also tracked in the GAME Modules repository.

NOTE: PD is a transparent, orchestration layer between the Evaluator and Predictor. It forwards payloads without modifying them, but its batching and response reassembly depend on specific request/response keys (sequences, prediction_ranges, prediction_tasks, predictions, etc.). Its game_schema_version tracks which GAME schema PD’s split/merge logic is compatible with — schema changes that don’t touch those keys don’t require a PD update; changes that do, will.

How to check it#

Before running an evaluation, Predictor’s schema version can be verified with:

curl -X GET http://HOST:PORT/help

For Evaluators, Matcher, and the PD, the schema version from the container can be inspected with:

apptainer inspect --labels <image>.sif | grep game_schema_version

Module-level version#

Module-level versioning (via predictor_name / evaluator_name / matcher_version) tracks the specific build of a container. This is handled automatically by reading the container’s build-date label from Apptainer’s /.singularity.d/labels.json and appending it to the module’s base name in config.py. The format is YYYYMMDD-HHMMSS_TZ, producing names like DREAM-RNN_Human_K562_20260407-140628_PDT or "Matcher_20260414-171101_PDT".

This automatic versioning ensures that every rebuild of a container produces a unique, sortable identifier — allowing Evaluators to distinguish between different builds of the same Predictor, even when the API schema version has not changed. This is especially important when model weights, preprocessing logic, or dependencies are updated between builds, which can impact their prediction and therefore their evaluation outcomes.