Aeson format

The aeson format is used to output JSON from Berlioz

Basic rules

The default Aeson conversion rules:

  • XML elementsJSON objects
  • XML attributes → JSON properties
  • <json:array> → JSON arrays

The name of document element as well as any other type of node is ignored (comments, processing instructions, namespace declarations and nodes, text)

For example:

<root version="1.0">
  <person id="4" name="Ali Baba"/>

Will be serialized as

  "version": "1.0",
  "person": {
    "id": "4",
    "name": "Ali Baba"


To create arrays, use the <json:array> element.

For example:

  <person id="1" name="Bob"/>
  <person id="2" name="Alice"/>

Will become:

  {"id": "1", "name": "Bob"},
  {"id": "2", "name": "Alice"}


In the context of an object you need to provide a name! See below on how to do this.

Primitive types

By default, all attributes values are turned into the string JavaScript type. To turn some values into a different type, you can use the json:boolean and json:number attributes.

For example:

<document editable="true" final="false" json:boolean="editable final"
          version="514" json:number="version"/>

Will become:

{"editable": true, "final": false, "version": 514}


The are two ways to specify null values.

Attribute json:null

Just like json:number or json:string, the attribute can specify a list of attributes names to turn to null.

For example:

<json:object description="" json:null="description"/>

Will become:

{"description": null}

Element <json:null>

The <json:null> element is analogous to the <json:object> and <json:array> elements and can also take an optional json:name attribute. This form can be more convenient to insert null values inside objects or arrays.

For example:

  <json:null json:name="description">

Will become:

{"description": null}


Null is not valid directly in the root context of a JSON structure, Aeson will automatically replace any attempt to write only null by an empty object and throw a warning - this is not a bug! 

Inherited types

Since version 0.5, when a type is declared, it is automatically inherited to the descendant elements, so that the same type declaration does not have to be made too many times.

For example:

<document json:int="size">
  <file size="1024"/>

Will become

{"file": {"size": 1024}}


Note, you can override a type declaration by applying a different type to the same name.

Typed elements

Since version 0.5, elements which have no attributes and match given type can also be turned into properties (in objects) or values (in arrays).

Within objects

Inside an object, an element matching a type will be transformed into a property. For example:

<document json:string="title">
  <title>A great start!</title>

Will become:

{"title": "A great start!"}

(Without the string type declaration, it would have been {"title": {}} )

Within arrays

Inside an array, elements matching types will be transformed into values; this is usefule to construct arrays of primitives. For example:

<choice json:string="option">

Will become:


(Without the string type declaration, it would have been [{},{}] )


By default and if the context allows it, Aeson uses the name of the element for the JSON object it serializes into. In some cases, it is necessary to specify a name other than that of the element. For example, when the JSON name uses characters which aren't allowed as XML elements or for arrays in the context of an object.

For example:

  <json:array json:name="persons">
    <person id="1" name="Bob"/>
    <person id="2" name="Alice"/>
  <ignored json:name="<&gt:" />

Will become:

  "persons": [{"id": "1", "name": "Bob"},{"id": "2", "name": "Alice"}],
  "<>": {}


In the context of a object, you have to provide a name; if you don't and use either json:object or json:array, Aeson will use "object" and "array" respectively and send a warning to the console.


Document / Arrayelement(name){ ... }
Objectelement(name)name : { ... }
Document / Arrayattribute(name)ignored
Objectattribute(name)name : value
Document / Array<json:array/>[ ... ]
Object<json:array name=""/>name : [ ... ]
Document / Array<json:object/>{ ... }
Object<json:object name=""/>name : { ... }
Document / Array<json:null/>null
Object<json:null name=""/>name : null

JSON Attributes

json:nameProvide a name of the JSON object for the current element
json:booleanA list of attribute names to convert to a boolean
json:numberA list of attribute names to convert to a number
json:stringA list of attribute names to convert to a string (default)
json:nullA list of attribute names to set to null


The list of attributes are separated by spaces.

Error handling

In most situations, Aeson will not fail but will simply send a warning to the console.

Nodes which aren't serializable by Aeson such as text nodes, comments, processing instructions are simply ignored.

Warnings are sent in the following situation:

  • A name with json:name is specified in the context of an array or the root of the document
  • The json:name is missing when using json:array or json:object in the context of an object. Aeson will use "array" and "object" instead.
  • An attribute could not be converted to a boolean or number primitive type (when a json:boolean or json:number was used).


Since a JSON structure does not make use of namespaces, Aeson only uses the local name part of elements and attributes when serializing them.

To send instructions to the Aeson serializer, use the namespace. Elements and attributes on that namespace have a special meaning for the serializer.

Aeson will not attempt to serialize any element or attribute on the following namespaces:

  • reserved for xml:*
  • reserved for xmlns:*

Created on , last edited on