problem.xml

Documentation by Example

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.

Table of contents

• The example
• XML representation
• XML structure
  • XML declaration
  • problems
  • remark
  • problem
  • foreignid
  • piecedecls
  • release
  • author
  • source
  • award
  • twin
  • position
  • pieces
  • addition
  • removal
  • exchange
  • stipulation
  • endstate
  • length
  • solution
  • move

The example

Thomas Maeder PCCC 1989 3rd prize correction by 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#

XML representation

The XML representation of this problem that is referred to on this page is here.

XML structure

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.

XML declaration

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.

problems

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">
    

• count (optional): indicates the number of problems contained in the problems element
• title (optional): gives the document a title (much like this HTML page has a title)
• xmlns:xsi (required by subsequent attribute) declares xsi to be a prefix for an XML namespace; namespaces exist to structure the space of all names used in XML documents.
  The value of the attribute indicates that the names qualified with the prefix xsi are used as defined by w3.org, the Standardization organization of the Internet.
• xsi:schemaLocation (optional): indicates where the XML schema can be accessed which defines the format of the problems element and its children.
  Typically, names (of elements and attributes) are written with letters and decimal digits (plus _) only. In the name xsi:schemaLocation, the part after the colon (schemaLocation) is the actual name, while the part before the colon (xsi) refers to the namespace that the actual name belongs to.
• The other namespace declaration, xmlns="...", declares the namespace that contains the names that don't have a namespace qualification, e.g. problems, count and title and most of the other names occuring in the document. These names are part of the problem.xml Standard format.

remark

      <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

      <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

      <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

      <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:

• id (required): uniquely identifies the declared piece in the context of the containing problem element; it can have a human-readable value as in the example, but that is not a necessary requirement.
• kind (required): default kind of the piece
• color (required): default color of the piece

release

      <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:

• id (required): identifies the release element so that it can be referred to from base attributes of other release elements
• base (optional): specifies that the release element is based on the release element that has the value as its id attribute. No content is inherited from the base to the derived release element; the connection between base and derived release element merely serves to document the history of a problem.
• type (required): one of initial, correction or version. initial release elements shouldn't have the base attribute, while other release elements should have it.

author

      <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:

• family name and given names
• information formatted similary to a vCard

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

      <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

      <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.

twin

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:

• id (required): identifies the twin element so that it can be referred to from base attributes of other twin elements
• base (optional): specifies that this twin element is derived from the twin element with the same value as its id attribute. A derived twin element inherits all properties from its base twin element unless elements are overriden by elements of the same name in the derived twin element.
• type (optional): can be used to indicate zeropositions and duplexes.

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

      <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:

• id (required): identifies the position element so that it can be referred to from base attributes of other position elements
• base (optional): specifies that this position element is derived from the position element with the same value as its id attribute.
  A derived position element means that the represented position is to be set up starting at the base position. From there on, modifications can be done by either adding the above mentioned twinning elements and/or by adding a pieces element which adds, removes, moves or exchanges pieces.

pieces

      <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

      <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:

• piece (required): refers to a piece previously declared by a piecedecl element; the value of the piece attribute must be equal to that piecedecl element's id attribute
• kind (optional): if present, overrides the kind declared in the piecedecl element
• color (optional): if present, overrides the color declared in the piecedecl element

removal

      <removal piece="piece17"/>
    

(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:

• piece (required): refers to a piece previously declared by a piecedecl element; the value of the piece attribute must be equal to that piecedecl element's id attribute

exchange

      <exchange piece1="blackqueenf8" piece2="blackknightb8"/>
    

An exchange element causes two pieces to exchange places in the current position.

exchange elements have one attribute:

• piece1, piece2 (both required): refer to pieces previously declared by piecedecl elements; the value of both attributes must be equal to those piecedecl elements' id attributes

stipulation

      <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:

• order (required): order of the moves; currently, this attribute must have a value among alternating (alternating moves by both sides) or incremental (1 move by the first side, then 2 by the opposite side, then 3 by the first side etc.)
• play (required): kind of play; one of direct, help, self, reflex, semireflex, series
• structure (optional): in help play, this attribute may specify the (intended) structure of the solution (e.g. "2.1;1...")

endstate

      <endstate type="mate"/>
    

The endstate element specifies the state to be reached so that the stipulation is considered fulfilled.

endstate elements have one attribute:

• type (required): One of mate, stalemate, win or draw

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

      <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:

• type (required): Specifies if the length is a maximum value or if the number of moves has to match it exactly. One of maximum and exact
• value (required): number of moves that may be spent. This is an integral positive number; in help play, half moves are counted; in other plays, the value indicates the number of moves of the side that plays the first move

solution

      <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

      <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:

• id (required): identifies the move element so that it can be referred to from base attributes of other move elements
• parent (optional): specifies that the move element represents a move that follows after another move when the solution is played; the value must be equal to the id attribute of the move the represents that move
• type (required): Specifies the type of move; one of solution, variation, threat, try, refutation, set. In help and series play, the type attribute can only have the values try, set and solution; in direct, self and (semi)reflex play, white moves have type try, threat or solution and black moves set, variation or refutation.

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.