Sashité for Developers
  1. Sashité for Developers
  2. Specifications
  3. PON
  4. 1.0.0

Position Object Notation (PON) Specification

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 (Game, Match, Position, Board, Square, Hand, Piece, Piece Side, Piece State, Piece Style, Terminal Status, Active Player, Player Side) are defined in the Glossary.

PON does not redefine these concepts; it specifies how to encode a protocol-level Position as a JSON object.

2. Overview

Position Object Notation (PON) is a rule-agnostic Position encoding using JSON for two-Player, turn-based board games built on the Sashité Game Protocol.

A PON object encodes exactly:

  1. Board structure and occupancy (which Squares exist and which Pieces occupy them),
  2. Hands (collections of off-board Pieces located in each Player’s Hand),
  3. Styles (the Player Style associated with each Player Side),
  4. Turn (the Active Player).

PON is designed to be:

3. Scope and non-goals

3.1 What PON defines

PON defines:

3.2 What PON does not define

PON does not define:

4. Dependencies

PON depends on:

Token validity for EPIN and SIN is defined by their respective specifications.

5. Conformance

A valid PON object MUST satisfy:

  1. the structural rules defined in this specification,
  2. the type constraints for each field,
  3. the dimensional coherence rules for the Board,
  4. the cardinality constraints inherited from the Game Protocol.

Requirements:

6. Overall structure

A PON object consists of four fields:

{
  "board": <BOARD>,
  "hands": <HANDS>,
  "styles": <STYLES>,
  "turn": <TURN>
}

All four fields are required.

6.1 Field summary

Field Type Description
board array Multi-dimensional array representing Board structure and occupancy
hands object Pieces held in each Player’s Hand
styles object Player Style for each Player Side
turn string The Active Player’s Side

6.2 Encoding

PON documents MUST be valid JSON per RFC 8259 and encoded in UTF-8.

7. Field 1 — Board

The board field encodes Board structure and occupancy as a multi-dimensional array.

7.1 Structure

The board field is a nested array structure where:

7.2 Square representation

Each Square is represented by one of:

7.3 Dimensional model

The dimensionality of the Board is determined by the nesting depth of the board array:

Nesting depth Dimensionality Structure
1 1D Single array of Squares
2 2D Array of ranks
3 3D Array of layers, each containing ranks
N ND N-1 levels of nested arrays, innermost being ranks

7.4 Board serialization scheme (required external context)

To interpret a board array as Squares on a Board, the surrounding Game context MUST define a deterministic Board serialization scheme, including:

PON preserves array structure and nesting, encoding dimensional structure without assigning geometric meaning.

7.5 Dimensional coherence

The board array MUST be rectangular at each level of nesting:

7.6 Non-emptiness

The board array MUST contain at least one Square. An empty Board is not valid.

8. Field 2 — Hands

The hands field encodes the two protocol Hands as an object with two properties.

8.1 Structure

{
  "first": <FIRST_HAND>,
  "second": <SECOND_HAND>
}

Where:

Both properties are required. An empty Hand is represented as an empty array [].

8.2 Hand items

Each Hand is an array of strings, where each string is a valid EPIN token.

8.3 Ordering

The ordering of Pieces within a Hand array carries no semantic meaning.

Implementations SHOULD order Hand arrays consistently for readability (e.g., alphabetically by EPIN token), but this is not required.

8.4 Piece Side independence

The Piece Side encoded inside the EPIN token is a property of the Piece itself and is independent of the Hand’s associated Side.

A Piece with Piece Side first (uppercase letter) MAY be located in the Second Player Hand, and vice versa.

9. Field 3 — Styles

The styles field encodes the Player Style associated with each Player Side.

9.1 Structure

{
  "first": <FIRST_STYLE>,
  "second": <SECOND_STYLE>
}

Where:

Both properties are required.

9.2 SIN token constraints

Each Style value MUST be a valid SIN token (exactly one ASCII letter).

The case of the SIN token encodes the Player Side:

9.3 Style semantics

The meaning of each Style letter is context-dependent and defined by the Rule System or application. PON does not assign any semantic meaning to specific letters.

10. Field 4 — Turn

The turn field identifies the Active Player.

10.1 Structure

The turn field MUST be one of:

11. Validation requirements

11.1 Structural validation (required)

An implementation MUST:

  1. Verify the input is valid JSON.
  2. Verify the root is an object with exactly four properties: board, hands, styles, turn.
  3. Validate board:
    • is an array,
    • is non-empty (contains at least one Square),
    • has consistent rectangular structure at each nesting level,
    • each leaf element is either null or a valid EPIN token.
  4. Validate hands:
    • is an object with exactly two properties: first and second,
    • each property is an array,
    • each array element is a valid EPIN token.
  5. Validate styles:
    • is an object with exactly two properties: first and second,
    • first is a valid uppercase SIN token (A–Z),
    • second is a valid lowercase SIN token (a–z).
  6. Validate turn:
    • is a string,
    • is either "first" or "second".

11.2 Cardinality validation (required)

An implementation MUST reject PON objects that violate the cardinality constraints inherited from the Game Protocol.

Let:

The following constraints MUST be satisfied:

Constraint Requirement Rationale
Board non-empty n ≥ 1 A Board must contain at least one Square
Piece cardinality p ≤ n The number of Pieces cannot exceed the number of Squares

Note: A Position with zero Pieces (p = 0) is valid, provided the Board contains at least one Square.

11.3 Extended validation (optional, context-dependent)

If the Game context is known, implementations MAY additionally validate:

12. Robustness considerations

Implementations SHOULD defend against resource abuse:

13. Design properties

PON is designed to be:

14. Examples

See PON Examples for comprehensive usage patterns including:

15. JSON Schema

A JSON Schema for PON is published for programmatic validation:

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

16. Reference implementations

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

They generally provide:

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

17. 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)”.