This text is an attempt to document the current status of problem.xsd. It is based on an example XML document which obeys to the requirements stipulated in problem.xsd.
This text is not a full reference; for more accurate information, refer to the XML Schema Documentation.
Thomas Maeder, Harry Fougiaxis, Pavlos N. Moutecidis & Costas Prentos
The Problemist vol. 13 no. 8, III-1990
h#2 b) bQf8 <-> bSb8
a) 1.Qxc8 f8Q+ 2.Qd7 Qc8#
b) 1.Sxe6 f8S+ 2.Sg7 Se6#
The original position had the black bishop on b8, a black pawn on d6, the lower black rook on a2 and the black pawn on b2; the twinning replaced the black queen f8 by a knight. Twin a) was cooked by 1.~ Sc6 2.Qe8 fxe8Q#
The XML representation of this problem that is referred to on this page is here.
In the following, the same terms are sometimes used to denote XML concepts and sometimes to denote "real life" entities. Different fonts are used to tell these two usages of terms apart: monospace is used for XML concepts and a regular font for real life entities.
As every "decent" XML document, we start with the XML declaration:
<?xml version="1.0" encoding="ISO-8859-1"?>
The XML declaration specifies the version of XML a document is written in, and the character encoding of the document.
The example document uses the ISO-8859-1 (also known as "Western") character encoding; this encoding is commonly used on Windows and Linux computers in Western Europe and the USA. The ISO-8859-1 encoding is a so-called 8bit encoding, i.e. it allows only 256 (2 to the power of 8) different characters to be present in a document (of which several are "unprintable"). This encoding doesn't allow the names of the three Greek authors of the example problem to be natively represented. If a document is to contain all names in their native form, a Unicode encoding (such as UTF-8) can be used instead.
The remainder of the file consists of nested XML elements, with a single element, the root element, on the first nesting level. In the example document (and in most other documents that follow problem.xsd), the root element is a problems element.
The root element of a document that obeys to problem.dtd is usually a problems element, since such a document is supposed to contain chess problems. The problems element is structured as follows:
<problems> <problem> ... </problem> <problem> ... </problem> ... <remark> ... </remark> </problems>
I.e. a document consists of a number of problem elements, followed by a remark.
The opening tag of the problems element has a number of attributes:
<problems xmlns="http://www.sci.fi/~stniekat/pccc/2007/Problem/1/0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="..." count="1" title="An XML example">
<remark> <signature> <by>Thomas Maeder</by> <date> <day>13</day> <month>04</month> <year>2003</year> </date> </signature> <text>Partially generated from the PDB, partially typed in by hand</text> </remark>
The remark element is used as a part of various elements to give information that doesn't otherwise fit into the element structure.
<problem> <foreignid> ... </foreignid> <foreignid> ... </foreignid> ... <piecedecls> ... <piecedecls> <release id="r1.1" type="initial"> ... </release> <release id="r1.2" base="r1.1" type="correction"> ... </release> ... </problem>
A problem element consists of 0 or more foreignid elements, a piecedecls element and 1 or more release elements; it can also contain other elements such as remark, theme, uncertainty, and references.
<foreignid> <domain>PDB</domain> <problemid>P0540993</problemid> </foreignid>
A foreignid element indicates how the problem is identified in other sources. The domain indicates the collection or database, and the problemid identifies the problem withint the domain. The example problem has PROBID P0540993 in the PDB.
<piecedecls> <piecedecl id="whitekinga5" kind="king" color="white"/> <piecedecl id="whiterookh7" kind="rook" color="white"/> ... </piecedecls>
The piecedecls elemment contains one or more piecedecl elements which declares one piece used in the problem.
piecedecl elements have tree attributes:
<release id="r1.1" type="initial"> <author> ... </author> <source> ... </source> <award> ... </award> <twin id="t1.1"> ... </twin> <twin id="t1.2" base="t1.1"> ... </twin> ... <correctness> ... </correctness> </release>
A release element represents a stage during creation of the problem, from preliminary versions over the initially published setting to eventual corrections and/or improvements. Apart from the elements given above, text and reprint elements are possible "children" of a release element.
release elements have three attributes:
<author> <authorname transcription="local"> <familyname>Maeder</familyname> <givennames>Thomas</givennames> </authorname> </author> <author> <authorname transcription="local"> <familyname>Fougiaxis</familyname> <givennames>Harry</givennames> </authorname> </author> <author> <vCard:VCARD> ... </vCard:VCARD> </author> ...
The author element indicates one author of a release; if a release has multiple authors, an author element is added for each. An author can currently be indicated by one of two ways:
For using the former way, make an authorname element the child of the author element.
If more information than just family name and given names is required (e.g. for FIDE Album entries), use a VCARD element as child of the author element; a VCARD element has children similar to the fields of a vCard (an industry Standard for exchanging address data). Since VCARD and its child elements are not part of this Standard format, their names have to be qualified with the namespace vCard.
<source> <name>The Problemist</name> <volume>13</volume> <issue>8</issue> <date> <month>3</month> <year>1990</year> </date> </source>
A source element identifies the place and date when a release was published. The date of publication can be specified as accurately as appropriate. If the source is a daily/weekly/monthly etc. periodical, day and or month can (should?) be given and the addition of elements such as number, volume, issue and problemid is encouraged.
Other allowed elements in the source element are remark and tourney; the latter will be used if the problem was published in a magazine in the context of a tourney award.
An alternative to all these elements is the text element, which may be useful e.g. if the whereabouts of the publication aren't well known.
<award> <tourney> <name>WCCC Quick composing tourney</name> <date><year>1989</year></date> </tourney> <distinction>3rd prize</distinction> </award>
An award element represents one award that the release was attributed.
The name twin for this element may be considered misleading, since real twin problems are represented by two twin elements, triplets by three, etc., and most problems will only have one twin element.
<twin id="initial_a"> <position id="initial_a"> ... </position> <stipulation order="alternating" play="help" structure="1.1..."> ... </stipulation> <solution> ... </solution> </twin> <twin id="initial_b" base="initial_a"> ... </twin>
twin elements have three attributes:
The example problem has two twin elements. The first twin element is the base of the second, which inherits the position from the first and modifies it, and has a different solution; the stipulation, however, is inherited unmodified.
The equality of the id attributes of the twin and position elements is concidential.
<position id="initial_a"> <pieces> ... </pieces> </position>
In the first twin of a release, the position element typically consists of a single pieces element. If in subsequent twin elements, the position element is derived from a previous position element, rotation, translation, reflection, swapcolors and aftermove elements can be used to specify the respective twinnings.
The retro element can be used in a position element for providing retro-analytical information.
position elements have two attributes:
<pieces> <addition piece="whitekinga5"> ... </addition> <addition piece="whiterookh7"> ... </addition> ... </pieces> ... <pieces> <exchange piece1="blackqueenf8" piece2="blackknightb8"/> </pieces>
In the pieces element, the placement of the pieces in the current position is defined. This is typically done by a series of addition elements. If we are in a twin position, removal or exchange elements may occur as well.
<addition piece="blackrooka2"> <plane dim="1" value="1"/> <plane dim="2" value="2"/> </addition>
An addition element causes a piece to be added to or moved in the current position.
The plane child elements identify the square where the piece is added or moved to. On a 2dimensional board, the plane element with dim="1" identifies the column while the plane element with dim="2" identifies the file; in the example, the piece is thus added on a2. This method of identifying squares may seem complicated; it was chosen to extend well to higher dimensions.
If an addition occurs to a square already occupied by a piece, that piece is removed from the board. If the piece attribute refers to a piece already on the board, that piece is moved to the indicated square.
addition elements have three attributes:
(The example problem doesn't contain a removal element, so this example element is made up.)
A removal element causes a piece to be removed from the current position.
removal elements have one attribute:
<exchange piece1="blackqueenf8" piece2="blackknightb8"/>
An exchange element causes two pieces to exchange places in the current position.
exchange elements have one attribute:
<stipulation order="alternating" play="help"> <length type="maximum">4</length> <endstate type="mate"/> </stipulation>
The stipulation element specifies the stipulation of the current twin.
stipulation elements have three attributes:
The endstate element specifies the state to be reached so that the stipulation is considered fulfilled.
endstate elements have one attribute:
Alternatively, a stipulation can be considered fulfilled if another stipulation can be fulfilled starting at the reached position; e.g. in a ser-h#5, the series stipulation is considered fulfilled if after 4 series moves, a position is reached from which a h#1 is possible. To allow such recursive stipulations to be expressed, a stipulation element can recursively contain another stipulation element instead of an endstate element. Cf. reference of the stipulation element for details.
<length type="maximum" value="4"/>
The length element specifies how many moves may be spent for reaching the end state.
length elements have two attributes:
<solution> <move id="a_b1" type="solution"> ... </move> ... <move id="a_cook_w1" type="set"> ... </move> ... <movetext after="a_cook_w1">and many more full-length cooks</movetext> ... <move id="some_other_solution" type="set"> ... </move> ... <signature> ... </signature> </solution>
The solution element specifies the entire solution of the twin. It consists of an arbitrary number of move and movetext elements and should be terminated by a signature element that gives information about how the solution was determined (program and version, human, ...).
movetext elements will typically be used to add some textual explanation about a variation, try or solution.
<move id="initial_a_sol_w1" parent="initial_a_sol_b1" type="solution"> <change piece="blackqueenf8"> <plane dim="1" value="3"/> <plane dim="2" value="8"/> </change> <text>model mate</text> </move>
Each move element represents a move.
move elements have three attributes:
A move element consists of one or more change elements. Normally a change element moves a formely declared piece to a new square, which is indicated as in the addition element.
Additionally, a move element can contain a symbol child element for marking up modern "letter themes", and a text child element that can represent text about the move or the position resulting from the move.