Qualified Piece Identifier (QPI) Specification

Version: 1.0.0
Author: Cyril Kato
Published: July 11, 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, Match, Piece, Piece Identity, Piece Name, Piece Side, Piece State, Piece Style, Terminal Status, Terminal Piece, etc.) are defined in the Glossary and are not redefined here.

2. Overview

Qualified Piece Identifier (QPI) is a rule-agnostic format for identifying Pieces in abstract strategy board Games by combining:

a SIN token (from SIN), and
a PIN token (from PIN),

separated by a colon.

A QPI token has the structure:

<sin>:<pin>

QPI encodes complete Piece Identity as defined in the Glossary: the tuple of five attributes that characterizes a Piece’s functional identity.

Piece Attribute	QPI Source
Piece Name	PIN
Piece Side	PIN
Piece State	PIN
Piece Style	SIN
Terminal Status	PIN

In addition, QPI defines a Native/Derived relationship that is deterministically derived from the token itself by comparing the case of the SIN letter with the case of the PIN letter.

This relationship is not part of Piece Identity. Its interpretation (if any) belongs to the Rule System.

2.1 Design rationale

QPI is designed as a compact, ASCII-only identifier that:

completes PIN by adding an explicit Piece Style abbreviation via SIN,
preserves the compactness and composability of primitive notations,
and enables a purely structural Native/Derived relationship via case comparison, without assuming any Game-specific semantics.

QPI is intentionally agnostic: it does not assume how a Rule System interprets Styles, Sides, conversions, Capture mechanics, ownership, legality, or outcomes.

2.2 Scope

QPI defines only:

the syntax of a QPI token,
how SIN and PIN are combined,
the mapping to Piece Identity attributes,
and the Native/Derived relationship derived from case comparison.

2.3 Non-goals

QPI does not define:

which Styles or Piece Names exist in a given Game,
how Pieces with a given Style move or behave,
what “enhanced” / “diminished” means in gameplay,
what “terminal” implies for legality or outcomes,
any notion of legality, Capture semantics, Promotion rules, repetition rules, clocks, or scoring,
any global constraint about how many Styles exist, are used, or are assigned during a Match.

Those concerns belong to the Rule System.

3. Dependencies

QPI depends on two primitive specifications:

SIN v1.0.0 — provides the Style abbreviation and a Side tag via letter case
PIN v1.0.0 — provides Piece Name, Piece Side, Piece State, and Terminal Status

QPI does not depend on any specific Game or Rule System.

4. Format Specification

4.1 Structure

A QPI token is defined as:

<sin>:<pin>

where:

<sin> is a valid SIN token,
: is the literal colon separator,
<pin> is a valid PIN token.

4.2 Grammar (EBNF)

qpi   ::= sin ":" pin ;

For the sin production, see the SIN specification. For the pin production, see the PIN specification.

Independence of cases (normative):

The case of <sin> and the case of the letter in <pin> are independent.
Producers MAY choose either case for <sin> and for the PIN letter independently.
Consumers MUST NOT assume they match unless explicitly using the Native/Derived definition in §5.

4.3 Regular Expression

A QPI token MUST match the following regular expression, anchored to the whole string:

\A[A-Za-z]:[-+]?[A-Za-z]\^?\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 anchors 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.
Implementations MUST reject any input containing line breaks (\r or \n).

5. Native and Derived Relationship

This section defines a derived relationship computed from the token itself. It is normative and requires no external context.

5.1 SIN case as a Side tag

A QPI implementation MUST interpret the case of <sin> as a Side tag:

uppercase <sin> → sin.side = first
lowercase <sin> → sin.side = second

This mapping uses the same two-Side convention (first/second) as defined in the Glossary.

5.2 Definition (normative)

Let:

sin.side be the Side tag encoded by the case of <sin> (§5.1),
pin.side be the current Piece Side encoded by the case of the PIN letter.

A QPI token is Native iff:

sin.side == pin.side

Otherwise, it is Derived.

sin.side	pin.side	relationship
first	first	Native
first	second	Derived
second	first	Derived
second	second	Native

5.3 Semantics (non-normative)

The terms Native and Derived in QPI express only this case relationship. Any additional interpretation (e.g., “original ownership”, “conversion”, “Capture”, “Drop eligibility”, etc.) is Rule System-defined.

6. Mutations and QPI Transformations

Piece attributes may change via Mutation. QPI can represent these changes without ambiguity because each attribute has a dedicated encoding location.

The following statements describe how a change in a single attribute affects the QPI token:

Piece Side change → only the case of the PIN letter changes.
Piece Name change → only the PIN letter identity changes (case continues to encode Piece Side).
Piece State change → the optional PIN state modifier changes (+, -, or absent).
Terminal Status change → the optional PIN terminal marker (^) is added or removed.
Piece Style change → the SIN component changes to another valid SIN from the Match context.

QPI does not prescribe when these changes occur; that is entirely Rule System-defined.

6.1 SIN stability within a Match (informative)

Within a Match, each Player has a fixed Player Side and a fixed Player Style. This means that exactly two SIN values are valid for the duration of a Match:

If both Players share the same Style (e.g., Chess), the valid SINs differ only by case (e.g., C and c).
If Players have different Styles (e.g., Chess vs Makruk), the valid SINs differ by letter (e.g., C and m).

Consequently, a Piece Style change during a Match means replacing the SIN component with the other valid SIN from the Match—not arbitrarily changing its case. The native and derive transformation methods (§7.3) operate on the PIN component, not the SIN component, precisely because of this constraint.

7. Parsing and Conformance Requirements

7.1 Validity

A string is a valid QPI 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.

7.2 Canonical form

QPI tokens are canonical by construction. There is no normalization required.

Implementations MUST NOT rewrite tokens by changing cases, rewriting modifiers, or applying any context-dependent mapping. In particular, tokens that differ only by letter case are distinct because case carries Side information.

7.3 Component extraction

Implementations SHOULD provide accessors for each component:

Accessor	Description
`sin`	A valid SIN token
`pin`	A valid PIN token
`native?`	Boolean: true iff `sin.side == pin.side`
`derived?`	Boolean: true iff `sin.side != pin.side`

Implementations SHOULD also provide transformation methods:

Method	Description
`native`	Returns a copy with Native relationship (PIN case aligned with SIN case)
`derive`	Returns a copy with Derived relationship (PIN case opposite to SIN case)

These methods are idempotent: applying native to a Native token or derive to a Derived token returns an equivalent copy.

Important: These methods MUST modify the PIN component (specifically, the case of the PIN letter), never the SIN component. This reflects the constraint that within a Match, each Player has a fixed Player Side and a fixed Player Style. Consequently, the SIN case (which encodes the combination of Style and Side) remains stable throughout a Match, while the PIN case (which encodes the current Piece Side) may change via Mutation.

7.4 Invalid token examples

String	Reason
`""`	Empty string
`C`	Missing colon and PIN
`C:`	Missing PIN
`:K`	Missing SIN
`CK`	Missing colon separator
`CC:K`	SIN has more than one character
`C:KK`	PIN has more than one letter
`C:+`	PIN missing letter
`C:K^^`	PIN has multiple terminal markers
`C:++K`	PIN has multiple state modifiers
` C:K`	Leading whitespace
`C:K`	Trailing whitespace
`1:K`	SIN is not a letter
`C:1`	PIN letter is not a letter

8. Context and Mapping

8.1 Context dependency

QPI is intentionally context-dependent for resolving abbreviations:

each Style letter is mapped to a concrete Piece Style by the current context (Game, Rule System, or application),
each Piece letter is mapped to a Piece Name within that same context.

The same QPI token may acquire different human descriptions in different contexts, but the underlying structure remains stable.

8.2 Conventions (non-normative)

A context MAY define additional conventions regarding:

how Style abbreviations are assigned,
how Piece abbreviations are assigned,
whether the case of SIN is used to encode a particular meaning beyond the Side tag.

Such conventions are outside the scope of this specification. Conforming QPI parsers MUST remain valid even if no such conventions are provided.

9. Design Properties

QPI is designed to be:

Rule-agnostic — independent of concrete Game mechanics,
Complete — encodes all five attributes of Piece Identity in a single compact token,
Relationship-aware — defines a deterministic Native/Derived relationship via case comparison,
Mutable-aware — can represent all attribute changes permitted via Mutation,
Composable — easy to embed in other formats (Position encodings, Match records, catalogs),
ASCII-only — safe for plain-text storage, logs, and protocols,
Cross-style capable — explicitly identifies Piece Style, enabling multi-tradition or mixed-Style engines.

10. Examples

See QPI Examples for practical implementation guidance.

11. Reference Implementations

The following reference libraries are maintained by Sashité and are intended to be idiomatic, fully tested, and spec-accurate implementations of QPI 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 (sin, pin, native?, derived?),
transformation methods (native, derive) that modify PIN, not SIN,
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 — qpi.ex
Ruby — qpi.rb

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