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

Portable Chess Notation (PCN) Specification

Overview

Portable Chess Notation (PCN) is a comprehensive, JSON-based format for representing complete chess game records across variants. PCN leverages the Sashité ecosystem specifications, using CELL for multi-dimensional coordinates, HAND for reserve locations, QPI for piece identification, PMN for move representation, and FEEN for position representation, creating a unified and rule-agnostic game recording system.

PCN supports both traditional single-variant games and modern cross-variant scenarios where different players use different game systems.

Terminology

For complete definitions of terms used in this document, see the Glossary.

Dependencies

PCN builds upon five foundational Sashité specifications:

These specifications define the standardized formats that PCN uses for coordinate identification, reserve management, piece representation, move encoding, and position description.

Design Principles

JSON Structure

{
  "meta": {
    "name": "<string>",
    "event": "<string>",
    "location": "<string>",
    "round": "<integer>",
    "started_on": "<date>",
    "finished_at": "<datetime>",
    "href": "<url>"
  },
  "sides": {
    "first": {
      "name": "<string>",
      "elo": "<integer>"
    },
    "second": {
      "name": "<string>",
      "elo": "<integer>"
    }
  },
  "setup": "<feen_position>",
  "moves": [
    [<pmn_element>, <pmn_element>, <pmn_element>, ...],
    ...
  ],
  "state": {
    "status": "<status>",
    "winner": "<winner>"
  }
}

Field Specifications

Meta Section (Optional)

Standard game metadata following common conventions.

Field Type Description
name string Game or opening name
event string Tournament or event name
location string Venue or location
round integer Round number (≥ 1)
started_on date Game start date (ISO 8601)
finished_at datetime Game completion timestamp (ISO 8601)
href url Reference URL

Sides Section (Optional)

Player information for each side:

Field Type Description
first object First player information
second object Second player information

Player Object Fields:

Field Type Description
name string Player name or identifier
elo integer Elo rating (≥ 0)

Player-Style Association

The association between players and style casing remains fixed throughout the game:

This association follows the conventions established by Style Identifier Notation (SIN):

First player’s style (uppercase style identifier):

Second player’s style (lowercase style identifier):

This enables cross-style scenarios where captured pieces retain their original casing while being controlled by the capturing player.

Turn Indication

The order of styles in the FEEN position indicates whose turn it is:

This dual function enables both style attribution and turn identification, supporting hybrid configurations where different players use different piece systems.

Examples

Setup Section (Required)

Initial game configuration using Forsyth-Edwards Enhanced Notation (FEEN):

Field Type Description
setup string Complete FEEN position string

This approach provides several advantages:

Important: All piece identifiers must use ASCII letters (a-z, A-Z) as required by the Extended Piece Identifier Notation (EPIN) specification.

Moves Section (Required)

Sequence of game moves using Portable Move Notation (PMN) format. Each move is a PMN array representing one player’s complete turn.

Move Array Structure: Each element in the moves array is a PMN sequence representing the complete mechanical decomposition of one player’s turn.

State Section (Required)

Current game state:

Field Type Description
status string Current game status
winner string or null Game winner when finished, null for draws

Game Status Values:

Winner Values:

Examples

Standard Chess Game

{
  "meta": {
    "name": "King's Gambit",
    "event": "Club Championship"
  },
  "sides": {
    "first": {"name": "Alice", "elo": 1650},
    "second": {"name": "Bob", "elo": 1720}
  },
  "setup": "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c",
  "moves": [
    ["e2", "e4"],
    ["e7", "e5"],
    ["f2", "f4"],
    ["e5", "f4"]
  ],
  "state": {
    "status": "in_progress",
    "winner": null
  }
}

Completed Chess Game with Checkmate

{
  "sides": {
    "first": {"name": "Alice"},
    "second": {"name": "Bob"}
  },
  "setup": "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c",
  "moves": [
    ["e2", "e4"],
    ["e7", "e5"],
    ["d1", "h5"],
    ["b8", "c6"],
    ["f1", "c4"],
    ["g8", "f6"],
    ["h5", "f7"]
  ],
  "state": {
    "status": "checkmate",
    "winner": "first"
  }
}

Cross-Game: Chess vs Xiangqi

{
  "sides": {
    "first": {"name": "Chess Player"},
    "second": {"name": "Xiangqi Player"}
  },
  "setup": "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/PPPPPPPP/2C2C2/RHBEKBHR / C/x",
  "moves": [
    ["e3", "e4"],
    ["e7", "e5"]
  ],
  "state": {
    "status": "in_progress",
    "winner": null
  }
}

Mare King Victory

{
  "sides": {
    "first": {"name": "Alice"},
    "second": {"name": "Bob"}
  },
  "setup": "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c",
  "moves": [
    ["e2", "e4"],
    ["f7", "f6"],
    ["d1", "h5"],
    ["g7", "g6"],
    ["h5", "e8"]
  ],
  "state": {
    "status": "mare_king",
    "winner": "first"
  }
}

Relationship with Other Specifications

PCN serves as the comprehensive game recording layer in the Sashité ecosystem:

Specification Relationship to PCN
CELL Core dependency: Provides multi-dimensional coordinate format for board locations in PMN moves
HAND Core dependency: Provides reserve location notation ("*") for capture-and-drop mechanics in PMN
QPI Core dependency: Provides piece identification format throughout moves and positions
PMN Core dependency: Represents each player’s turn as atomic action sequences using CELL and HAND
FEEN Core dependency: Provides initial setup and enables position reconstruction
SIN Inherited through QPI/FEEN: Distinguishes different piece systems and variants
PIN Inherited through QPI: Foundation for piece identification with state modifiers

PCN unifies these specifications to provide complete game documentation, ensuring that any recorded game can be fully reconstructed, analyzed, and shared across different implementations and platforms with full support for multi-dimensional boards and reserve-based mechanics.

JSON Schema

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

Reference Implementations

This section lists available libraries and tools that implement the PCN specification.

Ruby