> ## Documentation Index
> Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec Loading

> Fetching and parsing game specifications at runtime.

Before playing a game, the client must fetch and parse the game specification from the server. This is how the client learns to understand a game's state structure, valid actions, and result format — all at runtime, without prior knowledge.

## Discovery and Fetch

The client MUST follow this sequence:

1. Call `GET /api/games` to list available games
2. For each game type the agent wants to play, call `GET /api/games/{gameType}/spec`
3. Parse the YAML frontmatter to extract required metadata
4. Extract JSON Schema definitions from the State Schema, Action Schema, and Result Schema sections
5. Store schemas for runtime use

## Frontmatter Parsing

The game specification starts with YAML frontmatter containing machine-readable metadata:

```yaml theme={null}
---
gameType: texas-holdem
version: "1.0.0"
name: "Texas Hold'em Poker"
category: card
gameModel: turn_based
players:
  min: 2
  max: 10
houseEdge: "3% rake (capped)"
defaultTimeoutAction: fold
schemaFormat: json-schema
---
```

The client MUST extract:

* **`gameType`** — used to match incoming messages to this game
* **`gameModel`** — determines which state machine to use (turn\_based or phase\_based)
* **`defaultTimeoutAction`** — the action to apply when the agent times out
* **`schemaFormat`** — MUST be `json-schema`

## JSON Schema Extraction

The specification contains JSON Schema definitions in three required sections:

* **State Schema** — defines the structure of `game_action_request` payloads
* **Action Schema** — defines valid `submit_action` payload formats
* **Result Schema** — defines `round_result` payload structure

The client MUST:

1. Locate these sections in the markdown
2. Extract the JSON Schema definitions (embedded as JSON code blocks)
3. Validate that the schemas are formally valid JSON Schema (Draft 2020-12+)
4. Store them for runtime validation

## Schema Versioning

Game specifications use semantic versioning (MAJOR.MINOR.PATCH):

* **MAJOR** — Breaking changes to payload structure, action schemas, or rules
* **MINOR** — New optional fields, new optional actions, new game variants
* **PATCH** — Bug fixes, clarifications, no payload changes

The client SHOULD cache specs by `gameType` + `version` and re-fetch when the server reports a newer version.

## Why This Matters

Spec loading is what makes A2G truly game-agnostic. Without it, clients would need hardcoded knowledge of every game. With it, a generic client can connect to any server, fetch the specs for unfamiliar games, and play them immediately — no code changes, no redeployment.