Format

Warning!

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

Basic rules

The default Aeson conversion rules:

XML elements → JSON 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"/>
</root>

Will be serialized as

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

Arrays

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

For example:

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

Will become:

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

Warning!

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"/>
</document>

Will become

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

Note

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>
</document>

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">
  <option>Mash</option>
  <option>Fry</option>
</choice>

Will become:

["Mash","Fry"]

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

Naming

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:object>
  <json:array json:name="persons">
    <person id="1" name="Bob"/>
    <person id="2" name="Alice"/>
  </json:array>
  <ignored json:name="<&gt:" />
<json:object>

Will become:

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

Note

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.

Mapping

Context	XML	JSON
Document / Array	element(name)	{ ... }
Object	element(name)	name : { ... }
Document / Array	attribute(name)	ignored
Object	attribute(name)	name : value
Document / Array	`<json:array/>`	[ ... ]
Object	`<json:array name=""/>`	name : [ ... ]
Document / Array	`<json:object/>`	{ ... }
Object	`<json:object name=""/>`	name: { ... }
Any	namespace()	ignored
Any	text()	ignored
Any	comment()	ignored
Any	processing-instruction()	ignored

JSON Attributes

Attribute	Purpose
`json:name`	Provide a name of the JSON object for the current element
`json:boolean`	A list of attribute names to convert to a boolean
`json:number`	A list of attribute names to convert to a number
`json:string`	A list of attribute names to convert to a string (default)

Note

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

Namespaces

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 http://pageseeder.org/JSON 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:

http://www.w3.org/2000/xmlns/ reserved for xml:*
http://www.w3.org/XML/1998/namespace reserved for xmlns:*

Created on 18 November 2013 , last edited on 28 January 2016 at 12:53