The wire contract
Where it lives:
contract/cig2.schema.jsonis every type a CIG2 server sends or accepts, as JSON Schema (draft 2020-12).contract/openapi.jsonis the HTTP API, as OpenAPI 3.1.- A running server serves both at
GET /schemaandGET /openapi.json. cig context schemaprints 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]()}},
}
}