Portable Board Diff Notation

A general purpose JSON-based format for storing changes between actions of most abstract strategy board games.

Created
Updated
Status
beta

Abstract

This document proposes a format for representing changes between actions of most abstract strategy board games.

Status of this document

This document is a beta of the PBDN specification.

Copyright notice

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.


Introduction

PBDN (Portable Board Diff Notation) is a lightweight, JSON-based format that gives a consistent and easy way to represent changes between actions of most abstract strategy board games.

Compatible with multidimensional boards, easy for humans to read and write, and easy for machines to import and export, it is completely laws of game independent and compatible with most abstract strategy board games such as Draughts, Go and the main chess variants, including 장기Janggi, หมากรุกMakruk, 将棋Shogi, Western, 象棋Xiangqi. These properties make PBDN an ideal data-interchange format for storing changes between actions of most actors from abstract strategy board games such as pawns, pieces, kings, stones.

Notational conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Naming the board squares

Squares MUST be identified by a coordinate from an array that is a one-dimensional flattening of the board. E.g., on the starting position of a traditional Western chessboard, the square of the White Queen is 59 and the square of the White King is 60.

Specification goals

A specification for a portable move notation MUST observe the following criteria:

  1. The details of the system MUST be publicly available and free of unnecessary complexity.
  2. The details of the system MUST be non-proprietary so that users and software developers are unrestricted by concerns about infringing on intellectual property rights.
  3. The system MUST work for a variety of programs. The format SHOULD be such that it can be used by abstract strategy board game database programs, abstract strategy board game publishing programs, abstract strategy board game server programs, and abstract strategy board game playing programs without being unnecessarily specific to any particular application class.
  4. The system MUST handle abstract strategy board games which are playable by multiple sides.
  5. The system MUST be easily expandable and scalable. Examples: new actors, new games, new actions, new rules, etc.
    • The system MUST be cross-variants. It SHOULD be able to represent changes between actions where sides MAY play different abstract strategy board games such as Janggi, Go, Draughts, Shogi, Western, Xiangqi.
    • The system MUST handle move of boards of any dimension; e.g., 2D, 3D.
    • The system MUST handle move of boards of any size; e.g., 8x8, 9x9, 9x9x9.
    • The system MUST be able to fully describe actor actions according to a concerned Laws of Chess and the given chessboard structure.
  6. Finally, the system SHOULD handle the same kinds and amounts of data that are already handled by existing chess software and by print media.

How to serve PBDN

The use of the file suffix “.pbdn” is RECOMMENDED for files containing PBDN data.

When serving PBDN over HTTP, the media type “application/vnd.pbdn+json” is RECOMMENDED.

Notation

Resource representation

The JSON structure below shows the format of the resource:

[ {src_square}, {dst_square}, {piece_name} ]
Properties

The following table defines the properties that appear in this resource:

Property name Value Description
src_square unsigned integer Indicates a source square occupied by an actor.
dst_square unsigned integer Indicates a target square.
piece_name a string Indicates the name of the actor of the action.

Example

List of changes of the Immortal Game, in PBDN format:

  1. [ 52, 36, "C:P" ]
  2. [ 12, 28, "c:p" ]
  3. [ 53, 37, "C:P" ]
  4. [ 28, 37, "c:p" ]
  5. [ 61, 34, "C:B" ]
  6. [ 3, 39, "c:q" ]
  7. [ 60, 61, "C:-K" ]
  8. [ 9, 25, "c:p" ]
  9. [ 34, 25, "C:B" ]
  10. [ 6, 21, "c:n" ]
  11. [ 62, 45, "C:N" ]
  12. [ 39, 23, "c:q" ]
  13. [ 51, 43, "C:P" ]
  14. [ 21, 31, "c:n" ]
  15. [ 45, 39, "C:N" ]
  16. [ 23, 30, "c:q" ]
  17. [ 39, 29, "C:N" ]
  18. [ 10, 18, "c:p" ]
  19. [ 54, 38, "C:P" ]
  20. [ 31, 21, "c:n" ]
  21. [ 63, 62, "C:R" ]
  22. [ 18, 25, "c:p" ]
  23. [ 55, 39, "C:P" ]
  24. [ 30, 22, "c:q" ]
  25. [ 39, 31, "C:P" ]
  26. [ 22, 30, "c:q" ]
  27. [ 59, 45, "C:Q" ]
  28. [ 21, 6, "c:n" ]
  29. [ 58, 37, "C:B" ]
  30. [ 30, 21, "c:q" ]
  31. [ 57, 42, "C:N" ]
  32. [ 5, 26, "c:b" ]
  33. [ 42, 27, "C:N" ]
  34. [ 21, 49, "c:q" ]
  35. [ 37, 19, "C:B" ]
  36. [ 26, 62, "c:b" ]
  37. [ 36, 28, "C:P" ]
  38. [ 49, 56, "c:q" ]
  39. [ 61, 52, "C:-K" ]
  40. [ 1, 16, "c:n" ]
  41. [ 29, 14, "C:N" ]
  42. [ 4, 3, "c:-k" ]
  43. [ 45, 21, "C:Q" ]
  44. [ 6, 21, "c:n" ]
  45. [ 19, 12, "C:B" ]

See also
Informative References

This work is influenced by several documents.

Contributing

Want to make this page better? Make your changes and submit a hug request.