State Transition Notation (STN) Specification

Version: 1.0.0
Author: Cyril Kato
Published: June 13, 2025
License: Open Web Foundation Agreement 1.0

1. Status of this document

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirements.

Capitalized terms (Position, Board, Square, Hand, Piece, Active Player, Game Protocol, Rule System) are defined in the Glossary and the Game Protocol. This document does not redefine those terms.

2. Overview

State Transition Notation (STN) is a rule-agnostic, JSON-based format for describing state transitions in abstract strategy board games. STN captures the net changes between any two game Positions by recording modifications in Piece Locations, Hand/reserve contents, and Active Player status using standardized CELL coordinates and QPI Piece identification.

STN provides a precise way to represent position deltas without requiring knowledge of how those transitions were achieved. STN is purely a difference format — it describes the observable changes between two complete game Positions, including all aspects that define a Position: Piece Locations, reserve contents, and Active Player identity.

3. Dependencies

STN builds upon two foundational Sashité specifications:

Specification	Purpose
CELL	Multi-dimensional coordinate encoding for Board positions
QPI	Qualified Piece Identifier for unambiguous Piece identification

4. Scope

4.1 What STN defines

STN defines:

a JSON object structure for expressing position deltas,
field specifications for Board changes, Hand changes, and turn toggle,
validation rules for the format,
semantic interpretation of the delta format.

4.2 What STN does not define

STN is deliberately format-only. It does not define:

how transitions are achieved (that belongs to PMN or Rule Systems),
whether a transition is legal or valid,
game-specific constraints on Piece movements or captures,
any evaluation or outcome semantics.

All legality and game-specific semantics belong to Rule Systems, not to STN.

5. Format specification

5.1 JSON structure

An STN object is a JSON object with three optional fields:

{
  "board": {
    "<cell-coordinate>": "<qpi-piece | null>"
  },
  "hands": {
    "<qpi-piece>": <delta>
  },
  "toggle": <boolean>
}

All fields are optional. Each field represents changes to different aspects of the game Position.

5.2 Grammar (EBNF)

stn-object     ::= "{" [ field-list ] "}" ;
field-list     ::= field ( "," field )* ;
field          ::= board-field | hands-field | toggle-field ;

board-field    ::= '"board"' ":" board-object ;
board-object   ::= "{" [ board-entries ] "}" ;
board-entries  ::= board-entry ( "," board-entry )* ;
board-entry    ::= cell-key ":" ( qpi-value | "null" ) ;
cell-key       ::= json-string ;   (* Must conform to CELL specification *)
qpi-value      ::= json-string ;   (* Must conform to QPI specification *)

hands-field    ::= '"hands"' ":" hands-object ;
hands-object   ::= "{" [ hands-entries ] "}" ;
hands-entries  ::= hands-entry ( "," hands-entry )* ;
hands-entry    ::= qpi-key ":" integer-delta ;
qpi-key        ::= json-string ;   (* Must conform to QPI specification *)
integer-delta  ::= json-integer ;  (* Must be non-zero *)

toggle-field   ::= '"toggle"' ":" json-boolean ;

6. Field specifications

6.1 `board` field

Type: Object Purpose: Records changes to Piece positions on the Board

Maps CELL coordinates to their final state after the transition:

Key: CELL coordinate (string, MUST conform to CELL specification)
Value: QPI Piece identifier (string) or null (indicating empty Location)

Semantics:

Condition	Meaning
Key present, value is QPI	Location contains the specified Piece after transition
Key present, value is `null`	Location becomes empty after transition
Key absent	Location was not affected by the transition

Example:

{
  "board": {
    "e2": null,
    "e4": "C:P",
    "f3": "S:+N"
  }
}

6.2 `hands` field

Type: Object Purpose: Records changes to Piece counts in player reserves/Hands

Maps QPI Piece identifiers to net count changes:

Key: QPI Piece identifier (string, MUST conform to QPI specification)
Value: Non-zero integer delta (positive = Pieces added, negative = Pieces removed)

Constraints:

Values MUST be non-zero integers
Positive values indicate Pieces added to the reserve
Negative values indicate Pieces removed from the reserve

Example:

{
  "hands": {
    "S:P": -1,
    "S:B": 1,
    "c:q": 2
  }
}

6.3 `toggle` field

Type: Boolean Purpose: Indicates whether the Active Player changes during the transition Default: false when omitted

Value	Meaning
`false` (or omitted)	The Active Player remains the same after applying the transition
`true`	The Active Player changes after applying the transition

Example:

{
  "board": { "e2": null, "e4": "C:P" },
  "toggle": true
}

7. Semantic interpretation

7.1 Empty object behavior

{}

An empty STN object represents no changes to the Position:

No Board Locations change
No Hand/reserve contents change
Active Player remains the same (due to default toggle: false)

This represents scenarios such as:

Position comparisons with identical results
Null transformations
Baseline states for cumulative calculations

7.2 Minimal changes

Board-only change (no turn change):

{
  "board": {
    "e2": null,
    "e4": "C:P"
  }
}

Piece movement with same player remaining active.

Board change with turn change:

{
  "board": {
    "e2": null,
    "e4": "C:P"
  },
  "toggle": true
}

Standard move where turn passes to opponent.

Turn-only change (pass move):

{
  "toggle": true
}

Only the Active Player changes — no Board or Hand modifications.

Hand and Board change (drop):

{
  "hands": {
    "S:P": -1
  },
  "board": {
    "e5": "S:P"
  },
  "toggle": true
}

Piece drop from reserve to Board with turn change.

7.3 Complex transitions

Multi-piece movement (e.g., castling):

{
  "board": {
    "e1": null,
    "g1": "C:K",
    "h1": null,
    "f1": "C:R"
  },
  "toggle": true
}

Capture with state change:

{
  "board": {
    "e7": null,
    "e8": "C:Q",
    "f8": null
  },
  "hands": {
    "c:b": 1
  },
  "toggle": true
}

Cumulative multi-move delta:

{
  "board": {
    "e2": null,
    "e4": "C:P",
    "e7": null,
    "e5": "c:p"
  }
}

Net result of multiple moves with original player still active.

8. Validation rules

8.1 Structural validation

An STN document MUST satisfy:

JSON object — The document MUST be a valid JSON object.
Known fields only — The object MAY contain board, hands, and/or toggle fields.
Correct types — board MUST be an object, hands MUST be an object, toggle MUST be a boolean.

8.2 Format validation

An STN document MUST satisfy:

Valid CELL keys — Board keys MUST conform to the CELL coordinate specification.
Valid Board values — Board values MUST be valid QPI identifiers or null.
Valid QPI keys — Hand keys MUST conform to the QPI specification.
Non-zero deltas — Hand values MUST be non-zero integers.

8.3 Semantic validation

Semantic validation is application-specific. Implementations MAY validate:

QPI identifiers reference valid Piece types for the game context
CELL coordinates reference valid Board Locations for the game context
Hand modifications respect game-specific constraints

9. Design properties

STN is intended to be:

Rule-agnostic — Independent of specific game mechanics or rules.
Complete — Can represent any Position-to-Position transition.
Efficient — Only records what actually changed.
Composable — Multiple STN deltas can be combined for cumulative effects.
Bidirectional — Can be used to calculate reverse transitions.
Format-independent — Compatible with any Position representation system.
Pure diff semantics — Empty object means genuinely no changes.

10. Use cases

10.1 Position comparison

// Compare two positions and generate STN diff
const stn = calculatePositionDiff(positionA, positionB);

10.2 Incremental updates

// Apply STN delta to update position
const newPosition = applySTN(currentPosition, stnDelta);

10.3 Move validation

// Check if proposed changes are valid
const isValid = validateSTN(currentPosition, proposedSTN);

10.4 Undo/Redo systems

// Store STN deltas for reversible operations
const undoSTN = invertSTN(forwardSTN);

11. JSON Schema

A JSON Schema for STN is published for programmatic validation:

Schema URL: https://sashite.dev/schemas/stn/1.0.0/schema.json

Implementations MAY rely on this schema as a baseline validator and add further semantic checks as needed.

12. Examples

See STN Examples for practical implementation guidance and integration patterns.

13. Reference implementations

The following reference libraries are maintained by Sashité and are intended to be idiomatic, fully tested, and spec-accurate implementations of STN v1.0.0.

They generally provide:

strict parsing and validation (valid?, parse, and a raising/bang variant),
clear error reporting for invalid inputs.

If a library behavior appears to conflict with this document, this specification is normative. Please report issues (or propose clarifications) on the relevant repository.

Ruby — stn.rb

14. License

This specification is made available under the terms of the Open Web Foundation Agreement 1.0 (OWFa 1.0).

The authoritative legal text is the OWF “Final Specification Agreement (OWFa 1.0)”.

State Transition Notation (STN) Specification

1. Status of this document

2. Overview

3. Dependencies

4. Scope

4.1 What STN defines

4.2 What STN does not define

5. Format specification

5.1 JSON structure

5.2 Grammar (EBNF)

6. Field specifications

6.1 board field

6.2 hands field

6.3 toggle field

7. Semantic interpretation

7.1 Empty object behavior

7.2 Minimal changes

7.3 Complex transitions

8. Validation rules

8.1 Structural validation

8.2 Format validation

8.3 Semantic validation

9. Design properties

10. Use cases

10.1 Position comparison

10.2 Incremental updates

10.3 Move validation

10.4 Undo/Redo systems

11. JSON Schema

12. Examples

13. Reference implementations

14. License

6.1 `board` field

6.2 `hands` field

6.3 `toggle` field