Web Services Serialization Format

Linden Lab’s upcoming web services format is simple, consistent, robust, readable, flexible, and covers all necessary information faithfully represent REST systems.
We will represent all data with two container types for structure and a set of atomic types serialized to xml.

Atomic types:
* undefined
* boolean
* integer
* real
* uuid
* string
* binary
* date
* uri

Containers:
* array
* map

Attributes and Data

Attributes are only used for encoding parser and formatting instructions. The data in the elements is always data.

Root Element

The root element is llsd. The root must have only one child element which can be any container or atomic type.

Atomic Types

Each atomic type represents one value with type information. An atomic does not have a name, but may have attributes to specify format or processing considerations for the parser.
Consumers of atomics are encouraged to massage the data into the preferred native representation, but further serialization should honor the original type information if possible.

undefined

The undefined type is a placeholder to indicate something is there, but it has no value, and will be interpreted as a default value for any other atomic or container type at runtime.

Serialization example

<undef />

boolean

A true or false value.

Serialization examples

<!-- true -->
<boolean>1</boolean>
<boolean>true</boolean>
<!-- false -->
<boolean>0</boolean>
<boolean>false</boolean>
<boolean />

integer

A signed integer value with a representation of 64 bits.

Serialization examples

<integer>289343</integer>
<integer>-3</integer>
<integer /> <!-- zero -->

real

A 64 bit double as defined by IEEE.

Serialization examples

<real>-0.28334</real>
<real>2983287453.3848387</real>
<real /> <!-- exactly zero -->

uuid

A 128 byte unsigned integer.

Serialization examples

<uuid>d7f4aeca-88f1-42a1-b385-b9db18abb255</uuid>
<uuid /> <!-- null uuid '00000000-0000-0000-0000-000000000000' -->

string

A simple string of any character data which is intended to be human comprehensible.

Serialization examples

<string>The quick brown fox jumped over the lazy dog.</string>
<string>540943c1-7142-4fdd-996f-fc90ed5dd3fa</string>
<string /> <!-- empty string -->

binary data

A chunk of binary data.
The serialization format is allowed to specify an encoding. Parsers must support base64 encoding. Parsers may support base16 and base85.

Serialization examples

<binary encoding="base64">cmFuZG9t</binary> <!-- base 64 encoded binary data -->
<binary>dGhlIHF1aWNrIGJyb3duIGZveA==</binary> <!-- base 64 encoded binary data is default -->
<binary /> <!-- empty binary blob -->

date

A specific point in time. Intervals or relative dates are not supported. The serialization and parser only understand ISO-8601 numeric encoding in UTC. The time may be omitted which will be interpreted as midnight at the start of the day.

Serialization examples

<date>2006-02-01T14:29:53Z</date>
<date /> <!-- epoch -->

uri

A link to an external resource. The data is expected to conform to [http://www.ietf.org/rfc/rfc2396.txt rfc 2396] for interpretation, meaning, serialization, and deserialization.

Serialization examples

<uri>http://sim956.agni.lindenlab.com:12035/runtime/agents</uri>
<uri /> <!-- an empty link -->

Containers

Containers is a special data type which can contain any other data type including other containers.

map

A map of key and value pairs where key ordering is unspecified and keys are unique. The key is always interpreted as a character string and any character string is acceptable. If there are any elements in the map, it is serialized as a key followed by an atomic or container value. For every key, there must be one value.
Well formed and valid serialized maps may contain more non-unique keys. When a deserialized, the implementation should choose one of the the value objects, but that choice is not specified.

Serialization example

<map>
<key>foo</key>
<string>bar</string>
<key>agent info</key>
<map>
<key>agent_id</key>
<uuid>93c73b16-cd86-434d-8b4a-76e12eee950a</uuid>
<key>name</key>
<string>testtest tester</string>
</map>
</map>

array

An ordered collection of data members. Any member can be any atomic or container type.

Serialization example

<array>
<real>7343.0194</real>
<array>
<map>
<key>offset</key>
<integer>9847</integer>
</map>
<string>da boom</string>
</array>
</array>

xml-llsd DTD

<!DOCTYPE llsd [
<!ELEMENT llsd (DATA)>
<!ELEMENT DATA (ATOMIC|map|array)>
<!ELEMENT ATOMIC (undef|boolean|integer|real|uuid|string|date|uri|binary)>
<!ELEMENT KEYDATA (key DATA)>
<!ELEMENT key (#PCDATA)>
<!ELEMENT map (KEYDATA*)>
<!ELEMENT array (DATA*)>
<!ELEMENT undef (EMPTY)>
<!ELEMENT boolean (#PCDATA)>
<!ELEMENT integer (#PCDATA)>
<!ELEMENT real (#PCDATA)>
<!ELEMENT uuid (#PCDATA)>
<!ELEMENT string (#PCDATA)>
<!ELEMENT date (#PCDATA)>
<!ELEMENT uri (#PCDATA)>
<!ELEMENT binary (#PCDATA)>
<!ATTLIST string xml:space (default|preserve) 'preserve'>
<!ATTLIST binary encoding CDATA "base64">
]>

Example Output

<?xml version="1.0" encoding="UTF-8"?>
<llsd>
<map>
<key>region_id</key>
<uuid>67153d5b-3659-afb4-8510-adda2c034649</uuid>
<key>scale</key>
<string>one minute</string>
<key>simulator statistics</key>
<map>
<key>time dilation</key><real>0.9878624</real>
<key>sim fps</key><real>44.38898</real>
<key>pysics fps</key><real>44.38906</real>
<key>agent updates per second</key><real>nan</real>
<key>lsl instructions per second</key><real>0</real>
<key>total task count</key><real>4</real>
<key>active task count</key><real>0</real>
<key>active script count</key><real>4</real>
<key>main agent count</key><real>0</real>
<key>child agent count</key><real>0</real>
<key>inbound packets per second</key><real>1.228283</real>
<key>outbound packets per second</key><real>1.277508</real>
<key>pending downloads</key><real>0</real>
<key>pending uploads</key><real>0.0001096525</real>
<key>frame ms</key><real>0.7757886</real>
<key>net ms</key><real>0.3152919</real>
<key>sim other ms</key><real>0.1826937</real>
<key>sim physics ms</key><real>0.04323055</real>
<key>agent ms</key><real>0.01599029</real>
<key>image ms</key><real>0.01865955</real>
<key>script ms</key><real>0.1338836</real>
</map>
</map>
</llsd>

Guidelines

XML Encoding

When possible, prefer using us-ascii or or UTF-8 xml encoding.

\P/hoenix

This entry was posted in -Miscellaneous. Bookmark the permalink.

9 Responses to Web Services Serialization Format

  1. The root element is llsd.

    Linden LSD ?

  2. huuhuhuhuhuhuh…. ‘Lab’.

  3. AndrewLinden says:

    LLSD = Linden Lab Structured Data

  4. Bernd Elswit says:

    Added some discussions on that to the Wiki. Especially about the binary encoding, and a common element for Versioning.

  5. bedrop unattained heinousness hausen viscolize coinsurance theophilanthropy patible
    Thomas Saleen – Countywide Brokers
    http://www-history.mcs.st-andrews.ac.uk/Biographies/Dedekind.html

    日本語

  6. Burton Cash says:

    bedrop unattained heinousness hausen viscolize coinsurance theophilanthropy patible
    IntellectWorld.com – Chess Tactics
    http://www.hclibrary.us/ref/genlink.htm

    日本語

  7. Niks says:

    hii, i like the article you wrote. i also wrote an article on Serialization here : http://kaniks.blogspot.com
    feel free to post your comments

    thanks
    cheers

Comments are closed.