PGN Variations, Comments, Import/Export & Complete Records

PGN becomes powerful when a record contains more than the played moves.

It can also encode:

• alternative variations;
• comments;
• annotations;
• non-standard starts;
• supplemental metadata.

But the original standard also distinguishes two different formatting goals:

• permissive import;
• stricter canonical export.

Recursive Annotation Variations — RAV

RAVs use parentheses.

Example:

1. e4 e5 (1... c5 2. Nf3) 2. Nf3

The RAV represents an alternative sequence after backing up from the move immediately prior according to the PGN branch semantics.

RAVs may be nested.

Example:

1. e4 e5
(1... c5 2. Nf3 (2. Nc3 Nc6) 2... d6)
2. Nf3

PGN movetext is a tree-capable representation, not necessarily one flat line.

NAGs in PGN

NAG form:

• $n.

They provide machine-portable annotation semantics.

Example:

3. Bb5 $1

Traditional import suffixes can map to NAGs in export.

Do not confuse:

• $1

with:

• game move number;
• dollar amount;
• engine score.

SetUp + FEN

For non-standard starts:

[SetUp "1"]
[FEN "..."]

The movetext begins from the supplied FEN position.

This is essential for:

• composed studies;
• analysis fragments represented as games;
• games from variants/positions when applicable.

Variant-specific PGN conventions require a variant-aware implementation.

PGN import vs export

The original specification deliberately makes import format more tolerant.

Import format

Designed to accept hand-prepared data.

It can tolerate more formatting variability.

Export format

Designed for program-generated canonical output.

It is stricter so different programs can exchange data predictably.

A parser may accept more PGN than a canonical exporter should produce.

This is a general data-engineering concept:

• tolerant input;
• normalized output.

Canonical export vs modern software reality

PGN dates from the early 1990s.

Modern chess software frequently supports:

• extensions;
• extra tags;
• clock annotations;
• engine annotations;
• platform-specific metadata;
• relaxed parsing.

This creates an interoperability reality:

two applications may both say "PGN" while preserving different subsets of annotations/extensions.

PGN compatibility is not identical to perfect round-trip preservation across every vendor.

Practical database and analysis workflows add another layer beyond the core interchange format.

Reduced / minimal game records

The original spec defines a reduced export concept with:

• Seven Tag Roster;
• played moves;
• no comments;
• no RAV;
• no NAG.

This is useful for:

• bulk unannotated game storage;
• simple exchange;
• minimal examples.

A teaching page may also show a minimal pedagogical PGN when the goal is to explain one concept rather than every archival formatting detail.

Reading a complete PGN

Example:

[Event "Example Game"]
[Site "?"]
[Date "2026.08.26"]
[Round "1"]
[White "White"]
[Black "Black"]
[Result "1-0"]
[Annotator "Example"]

1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5
4. c3 Nf6 {A normal developing move.}
(4... d6 5. d4) 5. d4 exd4 6. cxd4 1-0

Read metadata first

• event;
• players;
• result.

Then movetext

• main moves;
• comment;
• variation;
• termination.

Writing a simple PGN

Workflow:

1. Verify game moves

Use legal position sequence.

2. Write STR

• Event;
• Site;
• Date;
• Round;
• White;
• Black;
• Result.

3. Blank line

Separate tag section.

4. Write movetext in SAN

Correct:

• move numbers;
• disambiguation;
• check/mate;
• castling;
• promotion.

5. Add optional comments/RAV/NAG

Only if needed.

6. End with termination marker

Match Result.

7. Validate with parser + rules engine

Syntax alone is insufficient because movetext moves must be legal from the evolving position.

A PGN validator needs both text parsing and chess-state reconstruction.

Complete game example — rules miniature

Consider this short legal miniature:

1. e4 e5 2. Nf3 Nc6 3. Bc4 d6 4. Nc3 Bg4
5. Nxe5 Bxd1 6. Bxf7+ Ke7 7. Nd5# 1-0

A simple PGN wrapper:

[Event "Rules Walkthrough"]
[Site "?"]
[Date "????.??.??"]
[Round "?"]
[White "White"]
[Black "Black"]
[Result "1-0"]

1. e4 e5 2. Nf3 Nc6 3. Bc4 d6 4. Nc3 Bg4
5. Nxe5 Bxd1 6. Bxf7+ Ke7 7. Nd5# 1-0

PGN limitations

PGN is historically important and still widespread, but it is not a perfect universal container for every modern chess application.

Limitations include:

• old specification design assumptions;
• differing vendor extensions;
• inconsistent preservation of comments/graphics/clock data;
• encoding practices beyond the original Latin-1-era text assumptions;
• variant interoperability differences;
• annotation round-trip differences.

PGN is a durable interoperability lingua franca, not a guarantee of identical behavior across every program.

Do not overstate obsolescence

The fact that PGN is old does not make it irrelevant.

It remains deeply embedded in:

• game databases;
• websites;
• engines/tools;
• publishing workflows.

The useful goal is format literacy and interoperable practice, not declaring an old format unusable merely because it is old.

PGN error classes

Tag syntax error

Malformed bracket/string/tag.

SAN error

Move token not canonical/valid.

Illegal movetext

SAN token parses but move cannot be legally played from current position.

Result mismatch

Result tag ≠ termination marker.

Variation error

RAV does not reconstruct from correct branch point.

Interoperability extension issue

File is accepted by one application but not another because of nonstandard metadata/extensions.

PGN practice

1. Identify STR tags.
2. Find supplemental tags.
3. Fix a Result mismatch.
4. Locate brace comment.
5. Locate RAV.
6. Locate nested RAV.
7. Convert !? import annotation to corresponding NAG concept.
8. Add SetUp/FEN to non-standard start.
9. Build minimal PGN from verified move list.
10. Explain why an accepted import file may not equal canonical export.

Why import and export have different goals

Human-authored data is messy. Program-generated data should be predictable.

That is the logic behind the classic PGN distinction:

• import tries to accept a useful range of valid or tolerable input;
• export aims to produce normalized output that other software can parse consistently.

The difference matters whenever you build tooling. "My parser accepts this file" is not proof that the same file is the best canonical output to generate.

Round-trip preservation is a separate question

Suppose application A imports a PGN containing:

• comments;
• nested variations;
• NAGs;
• clock annotations;
• custom tags.

Application B may understand the core game but ignore one extension. If the file is then exported again, the lost extension may not return.

This creates three distinct compatibility questions:

1. Can the application read the game?
2. Can it understand every annotation and tag?
3. Can it export all of that information again without loss?

A "yes" to the first question does not guarantee the other two.

Validating a complete PGN in layers

A useful validation pipeline is:

Text structure

• tag-pair syntax;
• comments;
• parentheses;
• tokens.

Metadata consistency

• required/common tags;
• result agreement;
• SetUp/FEN relationship.

Movetext syntax

• move numbers;
• SAN form;
• NAG/RAV placement.

Chess reconstruction

• each main-line move is legal from the evolving position;
• each variation begins from the correct branch point;
• SAN disambiguation and check/mate suffixes match the position.

Interoperability policy

• extensions are known, preserved, transformed or explicitly discarded according to your application rules.

This layered approach produces much better error messages than simply saying "invalid PGN".

Minimal records vs rich annotated records

A minimal game record is ideal when the purpose is:

• bulk storage;
• game identity;
• simple replay;
• lightweight exchange.

A rich annotated record is appropriate when you need:

• comments;
• alternative lines;
• training explanations;
• evaluations;
• source-specific metadata.

Neither is universally superior. The right record depends on what information must survive the workflow.

Frequently asked questions

Can a PGN contain more than one game?

Yes. PGN files commonly contain a sequence of game records. Each game has its own tag section and movetext.

If a chess site exports PGN, will another site preserve everything?

Not necessarily. Core moves and common tags usually interoperate well, but vendor-specific tags, clocks, arrows, evaluations or other extensions may be dropped or transformed.

Is old PGN still worth supporting?

Yes. Despite its age and limitations, PGN remains the dominant interchange language for conventional chess game records across databases, websites, publishing and analysis tools.

Key takeaways

PGN represents a full game record using:

• metadata tags;
• SAN movetext;
• termination.

It can also carry:

• comments;
• RAVs;
• NAGs;
• supplemental tags;
• FEN starts.

Critical safeguards:

• PGN ≠ just moves;
• Result tag = termination marker in canonical export;
• import can be permissive while export is strict;
• accepted extensions may not round-trip universally;
• moves remain position-dependent legal SAN.