View source for Changes to Metadata

==Stages in Drawing Shields==

In creating heraldic images DrawShield goes through several stages:

# Parse the blazon to create an Abstract Syntax Tree (AST)
# Draw an SVG representation of the blazon, based on the AST
# (optionally) convert the SVG to a different image format

The AST is an XML based data structure conforming to a custom schema called BlazonML.

==The MetaData==

Metadata ("data about data") in DrawShield comes from several sources:

* Debugging information to aid in problem solving
* Parsing errors (where the blazon is not understood, or has errors)
* Drawing errors (if the program understands the blazon, but is unable to draw what is requested)
* Artist credits to acknowledge the source of the images used in creating the final heraldic image

==Original MetaData Handling==

Originally, as the DrawShield program works through the various processing stages metadata is added to the AST, for example as &lt;message&gt; elements with an attribute to show the category of metadata. 

As the AST is held in XML format we can include all of this in the same SVG that we create for the heraldic image, since that is also XML data (technically, the SVG &lt;metadata&gt; element can contain %ANY% other elements, so we just include the whole of the AST, including all of our own metadata)
[[File:Original-metadata.png|alt=Original Data Flow|none|thumb|Original Data Flow]]

==Problems with the Original Approach==

Although this approach did "work" it raised a number of issues:

* It increased the size of the SVG files, sometimes doubling the required amount of data
* Although programs like Inkscape did handle and pass through the blazonML data other programs may have had problems with this "non-standard" SVG content
* All types of metadata, whatever their purpose, were lumped together in the same place (see below)
* When the data *was* needed it was awkward to access, requiring browser developer tools or an XML aware editor

In reality, the metadata has several different functions and "belongs" in different places:

* The parsing errors belong in the AST, since this is a representation of the ''blazon'', so errors in blazon itself should be included in that representation. These also need to be made easily available to the user as errors.

* Artist Credits belong with (or ideally, inside) the ''image'' of the blazon, in whatever format the user requested
* Problems with drawing the image need to be easily available to the user as warnings.
* The debug information is mostly of interest to developers, although some of it can be useful for a more detailed textual analysis

==Revised MetaData Handling==

For most purposes, what is required from DrawShield is an image in a particular graphics format that represents the entered blazon. Hence that is the "default" action, you will just get the image, in the format that you requested, with no extraneous data other than the artist credits where this is possible (currently in the rdf / creator element of SVG files, PNG and the other formats are being investigated).

If for some reason you require additional information then you can request a JSON file download. This will "package up" in a single file:

* The AST (in XML, and in a more compact, printable form)
* The corresponding image, in whatever format you requested (base64 encoded if binary)
* A set of printable messages for the user
* Debugging information, including all the options that were set, internal parser information, timings etc.
[[File:Revised-metadata.png|none|thumb|Revised Metadata Flow]]


By requesting a JSON file the callee can take whichever parts of the data are required and use it appropriately.

==Examples of Use==

The DrawShield "Create from a Blazon" page uses both methods. On the initial page load, all that is needed is a "blank" (argent) shield, but drawn with the currently selected preferences (appearance, shield shape etc.). We know that there are not going to be any errors so we just send an empty blazon (which is equivalent to "argent") and request an SVG file, which is then displayed on the page.

Once the user has entered a blazon and clicks the "Draw Shield" button we request a JSON file, containing the image in SVG format. The image is displayed on the page; the user messages are displayed as HTML and we might choose to display some of the debug information, such as timings.

Finally, if the user then chooses to download the image in a different format, e.g. PNG then we just request s single PNG image for download and that is all that we get.

Hence we get smaller downloads for simple purposes but have the option of a more complete, and more easily usable JSON download containing all the information. This can easily be used in other programs (JSON has wide-spread support in most programming languages). The end user can also request a download of the JSON file themselves (a new option on the "Save Shield" dialog), in which case we provide exactly the same data but present it with more new lines and whitespace for a more human-readable experience.

For details of how to make all these requests, see the API documentation, currently on Github at  [https://github.com/drawshield/Drawshield-Code/wiki/The-DrawShield-API The DrawShield API] 

 

[[Category:Discussion]]