Aeson is now part of Berlioz, go to Berlioz - Aeson format for the latest version.

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}

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: { ... }

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)


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