The wire contract

Where it lives:

  • contract/cig2.schema.json is every type a CIG2 server sends or accepts, as JSON Schema (draft 2020-12).
  • contract/openapi.json is the HTTP API, as OpenAPI 3.1.
  • A running server serves both at GET /schema and GET /openapi.json.
  • cig context schema prints the schema for the CIG2 version you build against.

How it is kept honest:

  • It is generated from the Go types the server actually marshals (go generate ./contract), so it cannot drift from the code.
  • CI fails if it is stale.
  • CI fails on a change that breaks existing clients, unless the CHANGELOG has a Migrate entry. “Breaking” means the server widening what it sends, or narrowing what it accepts.

Game-defined fields

Properties marked "x-cig2-game-defined": true (card payload and state, game_state, action data, decision prompt, table config) are shaped by each game. GET /describe returns the game’s own schemas for them, plus its rules and seat range, when the game implements cig2.GameDescriber.

Describe your game with schema.For[T]() on your own Go types. Never hand-write JSON Schema:

func (g *Game) Describe(any) cig2.GameDescription {
	return cig2.GameDescription{
		Rules:   "…",
		Seats:   &cig2.SeatRange{Min: 2, Max: 4},
		Actions: map[string]cig2.ActionDescription{"play": {Summary: "Play a card.", Data: schema.For[PlayData]()}},
	}
}