The JSON Output Format

The JSON Output Format

This format combines several items of useful data wrapped in a JSON object. It can be requested either as a file download or returned as an HTTP response, in either case the content is the same. In addition to specifying the 'outputformat' argument as 'json' you should also set the 'saveformat' argument to the type of image data that you would like the image to contain, if not given this will be 'png'.

Examples

To receive a JSON response containing a PNG image

POST/GET argument	Value
outputformat	json
saveformat	png
blazon	(as required)

To receive a file download containing an SVG image

POST/GET argument	Value
outputformat	json
saveformat	svg
asfile	1
filename	myfile.json
blazon	(as required)

JSON Objects

Top level object properties are as follows:

• blazon (string)

The requested blazon.

• creationTime (string)

RFC 2822 formatted date string based on the server time

• pathinfo (string)

server location of the program file used (on the DrawShield server this can be used to distinguish the release from the test versions as the paths are different)

• options (object)

This is the set of global options that were used to create the shield. These will either have been set elsewhere in the API call or take the default value. They are as described in the API page, although note that some of the names change (hopefully in obvious ways), for example the API argument 'ar' becomes 'aspectRatio' in the set of options.

• words (array of strings)

Each array entry is a single lexical item identified by the lexical analyser of the parser; followed in round brackets by its location within the blazon. Additionally, the lexical analyser can sometimes identify the type of the content, if so this is shown in square brackets.

• tree (string)

This is the result of the parsing stage and contains a representation of the blazon in XML, conforming to the blazonML schema. This is the "pure" parse tree before any rendering has been attempted.

• mintree (string)

This is a simplified, pretty-printed version of the parse tree which is sometimes easier to read. For example the input "azure a mullet or" will produce the mintree value of:

  shield ID=N1-9
    simple ID=N1-3
      field ID=N1-2
        tincture ID=N1-0 index=1 origin=given
          colour ID=N1-1 keyterm=azure tokens=azure linenumber=1/
        /tincture
      /field
      objects ID=N1-4
        charge ID=N1-6 number=1 tokens=a mullet linenumber=1 keyterm=mullet/mullet
          tincture ID=N1-7 index=1 origin=given
            colour ID=N1-8 keyterm=or tokens=or linenumber=1/
          /tincture
          modifier type=chargemod keyterm=chg_data ID=S1-2 value=chg1/
        /charge
      /objects
    /simple
  /shield

Note that is extracted after any cross-references have been resolved and so may contain additional rendering hints. For example the "chg_data" modifier is the key to a cached version of the information needed to draw mullets (for use when drawing multiple charges). I'm not sure how useful this actually is, _so this behaviour is subject to change_, it may in future be a simple extract from the simple parse tree above.

• messages (array of objects)

Each message object may contain the following properties:

• ID - (string - optional) if the message can be related to a specific part of the phrase tree this property gives value of the ID attribute of the relevant node
• category - (string) type of message, one of blazon / warning / internal / licence, all hopefully self-explanatory
• content - (string) the message text
• context - (string - optional) if this is an error message related to the blazon this is that part of the input blazon text in which the error occurred

• release (string)

A value which is incremented every time the DrawShield code is updated.

• reldate (string)

The date on which the DrawShield code was updated, from my development environment.

• image (string)

This is the shield image, in the requested format at the requested size. SVG format is provided as plain (but formatted) XML text data, the other formats are all encoded as base64 and will need to be decoded before use.

• memory (string)

A rough indication of how much memory was in use at various stages of the program

• timing (string)

Time, in seconds to execute various stages and the total elapsed time. Note that this is the server only and does not include any data transmission time.