Piece Identifier Notation (PIN) Specification

Version: 1.0.0
Author: Cyril Kato
Published: January 25, 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 (Game, Rule System, Piece, Piece Side, Piece Name, Piece State, Terminal Status, etc.) are defined in the Glossary.

2. Overview

Piece Identifier Notation (PIN) is a compact, ASCII-only token format used to encode a piece’s identity at the level of notation.

A PIN token encodes exactly these attributes:

Piece Name → a single-letter abbreviation chosen by the Game / Rule System,
Piece Side → the case of that letter (uppercase / lowercase),
Piece State → an optional prefix (+ or -),
Terminal Status → an optional suffix (^).

PIN is designed as a minimal building block that can be embedded in higher-level notations (positions, moves, catalogs).

Chess Pieces Board Sketch

2.1 Scope

PIN defines only:

the syntax of a token,
and how its characters map to the four attributes above.

2.2 Non-goals

PIN does not define:

Piece Style (movement tradition or family),
how pieces move,
what “enhanced” / “diminished” means in gameplay,
what “terminal” means in outcomes or legality,
how players are named (white/black, sente/gote, etc.),
any notion of legality, capture semantics, promotion rules, repetition rules, clocks, or scoring.

Those belong to the Rule System and (where relevant) the Game Protocol layer.

Note on Piece Style: The Game Protocol defines Piece Style as part of Piece Identity. PIN intentionally omits this attribute, leaving Style resolution to the surrounding context (e.g., game definition, position notation, or catalog metadata). This keeps PIN minimal and context-independent.

3. Dependencies

PIN is self-contained and has no dependencies on other Sashité specifications.

4. Token format

4.1 Structure

A PIN token is:

[<state-modifier>]<abbr>[<terminal-marker>]

Where:

<state-modifier> is optional and is either + or -,
<abbr> is exactly one ASCII letter (A–Z or a–z), serving as a single-letter abbreviation of the Piece Name,
<terminal-marker> is optional and is ^.

4.2 Grammar (EBNF)

pin              ::= [ state-modifier ] abbr [ terminal-marker ] ;
state-modifier   ::= "+" | "-" ;
abbr             ::= "A"…"Z" | "a"…"z" ;
terminal-marker  ::= "^" ;

4.3 Regular expression

A PIN token MUST match the following regular expression, anchored to the whole string (i.e. the pattern MUST match the entire input, from start to end):

^[+-]?[A-Za-z]\^?$

Anchoring requirement (normative):

Implementations MUST ensure the anchors apply to the entire input string, not to individual lines.
If the target regex engine interprets ^ and $ as line anchors under a multiline mode, implementations MUST disable that mode or use the engine’s “string anchors” equivalents to preserve whole-string matching.

Notes for implementers:

The ^ character in the pattern (before $) is a literal caret (escape it as required by your regex engine).
Tokens are case-sensitive.
Producers and consumers SHOULD treat any surrounding whitespace as invalid for a token (whitespace handling, if any, belongs to the surrounding container format, not to PIN itself).

5. Attribute mapping

A conforming implementation MUST interpret a valid token as follows.

5.1 Piece Name (via abbreviation)

The <abbr> letter serves as a single-letter abbreviation of the Piece Name, assigned by convention within a Game / Rule System.

The letter’s case is used to encode Piece Side (see §5.2), but the identity of the abbreviation is case-insensitive: K and k represent the same Piece Name abbreviation, differing only in which side owns the piece.

PIN does not reserve any letters; the mapping from abbreviation to full Piece Name is entirely Rule System-defined.

5.2 Piece Side

The case of <abbr> encodes Piece Side:

uppercase (A–Z) → Piece Side first,
lowercase (a–z) → Piece Side second.

This aligns with the two-side model defined in the Game Protocol.

5.3 Piece State

The optional <state-modifier> encodes Piece State:

absent → normal (baseline state),
+ prefix → enhanced state,
- prefix → diminished state.

PIN standardizes only the encoding. The Rule System defines the semantics of these states.

5.4 Terminal Status

The optional <terminal-marker> encodes Terminal Status:

absent → the piece is not a Terminal Piece,
^ suffix → the piece is a Terminal Piece.

PIN standardizes only the marking. The Rule System defines what Terminal Status implies for continuation, evaluation, and outcomes.

6. Parsing and conformance requirements

6.1 Validity

A string is a valid PIN token if and only if:

it matches the grammar in §4.2 (or the regex in §4.3),
and contains no extra characters (no whitespace, separators, or surrounding quotes as part of the token).

Implementations:

MUST reject invalid tokens,
SHOULD provide a non-raising validity predicate (e.g. valid?),
MAY provide a raising/bang parser variant.

6.2 Canonical form

PIN tokens are already canonical by construction:

at most one state modifier prefix,
exactly one ASCII letter as abbreviation,
at most one terminal marker suffix.

Implementations MUST NOT reorder or normalize tokens beyond strict validation. In particular:

K+ is invalid (modifier must be a prefix),
^K is invalid (terminal marker must be a suffix),
++K is invalid (only one modifier is allowed),
K^^ is invalid (only one marker is allowed).

6.3 Component extraction

Implementations SHOULD provide accessors for each component:

Accessor	Description
`abbr`	The single-letter abbreviation (always uppercase)
`side`	`first` or `second`
`state`	The state modifier (`normal`, `enhanced`, or `diminished`)
`terminal?`	Boolean indicating Terminal Status

7. Design constraints and considerations

7.1 Character space

PIN provides 52 base letters (A–Z and a–z) as abbreviations. With optional state modifiers and terminal marker, a context may use up to 312 distinct tokens (3 states × 2 terminal × 52 abbreviations).

7.2 Two-side assumption

PIN encodes exactly two Piece Sides (first/second) using case.

Games with more than two sides MUST use a convention outside the scope of PIN or use a different notation designed for multi-side encoding.

7.3 Abbreviation conventions

Since Piece Name is represented by a single-letter abbreviation, a Rule System SHOULD:

keep the mapping from abbreviation to full Piece Name stable and unambiguous within a given game context,
document which abbreviations correspond to which pieces,
document which pieces are designated as terminal.

7.4 Style omission

PIN intentionally omits Piece Style encoding. In contexts where Style matters:

the surrounding notation or metadata SHOULD provide Style information,
implementations MAY associate Style at a higher level (e.g., per-position or per-catalog).

8. Examples

See PIN Examples for practical mappings in various game contexts.

9. Reference implementations

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

They generally provide:

strict parsing and validation (valid?, parse, and a raising/bang variant),
round-trip serialization (string ⇄ structured identifier),
component extraction (abbr, side, state, terminal?),
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.

Elixir — pin.ex
Go — pin.go
Ruby — pin.rb

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