Aeson format

The aeson format is used to output JSON from Berlioz

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"}
]

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}

Nulls

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:object>
  <json:null json:name="description">
</json:object>

Will become:

{"description": null}

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}}

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"}],
  "<>": {}
}

Mapping

JSON Attributes

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 10 December 2015 , last edited on 28 January 2016 at 12:53