The JSON Output Format

The JSON Output Format

This format combines several items of useful data wrapped in a JSON object. Top level object properties are as follows:

• image (string)

This is the shield image, in PNG format at the requested size, but encoded as Base64 text. It is the identical image that you would have received had the output format been set to 'png'.

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

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

• 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 above, 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.

• 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 occcured