Object XML representation

In the Get object, Batch operation and Search APIs, objects are represented in XML as:

  • object
    • ref ? – objref of object, omitted if the object has not been stored yet
    • created ? – time of object creation (not updated when writing)
    • updated ? – time of object update (automatically updated when writing)
    • created_user ? – UID of creating user (not updated when writing)
    • updated_user ? – UID of updating user (automatically updated when writing)
    • attributes
      • included_attrs ? – comma separated lists of refs of attributes included. If this is not present, all attributes are included.
      • a *
        • d – ref of attribute (NEVER aliased attribute)
        • q ? – ref of qualifier, if attribute has a qualifier
        • vt – data type of value contained
        • X – value, see below

Note that aliased attributes cannot be used in objects; they are for display and editing only.

Value data representation

See Schema for the possible values of vt.

The values marked with X above depend on the data type. If vt < 16 (non-text type) the value is converted to text and output as a text node. There are some exceptions, documented below.

Text-like values are output as:

  • text + – text container nodes, more than one allowed to represent the same text in different languages
    • lang ? – language of the text
    • default ? – ‘true’ if this is the default language
    • TEXT – the text value.

Note: currently the UI doesn’t support multi-lingual text, so only the first text string is used.

Identifier values just output a single text element with no lang or default attributes.

Newline characters follow the UNIX conventions, with a single \n character.

Text types

There are various text formats, which are rendered to HTML differently.

Text (16)

Single line of text, rendered as is with HTML encoding. No newline characters should be included.

Paragraph text (24)

Single newline characters are turned into <br> HTML elements. Multiple newline characters indicate paragraph breaks.

Multiline text (33)

One or more newline characters are turned into <br> HTML elements.

Document text (25)

The TEXT value in the XML representation contains a serialised XML document fragment, XML encoded. XML parsers should return it as a string suitable for XML parsing itself.

When parsed, it returns a tree representing rich text with inserted widgets.

  • doc
    • p * – paragraph
      • TEXT – contained paragraph text
    • widget * – widget (eg object insertion, embedded search)
      • type – type of widget, see below
      • v * – value to specify options for the widget
        • name – name of the value
        • TEXT – value
    • sidebar, box, quoteleft, quoteright – containers
      • p * – as above
      • widget * – as above

The supported types and values of widgets are:

  • OBJ
    • ref – objref of object to include
    • style – render style. Most like to use only ‘generic’ or ‘linkedheading’
  • SEARCH
    • as per search spec in Searching API below, plus:
    • style – could be ‘mini’ or ‘cal’ for special rendering
    • limit – maximum number of results to return
    • within – “search within” user interface displayed above the search results. Could be ‘link’ or ‘field’, or left blank for no UI
  • HTML
    • html – raw HTML to output unencoded
  • FILE
    • name – filename of file to select from the containing object
    • img – 0 to link to the file, 1 to display inline
    • pos – position of inline image, ‘l’ = left, ‘m’ = middle, ‘r’ = right, ‘s’ = sidebar
    • size – size of inline image, ‘s’ = small, ‘m’ = medium, ‘l’ = large, ‘w[dim]’,‘h[dim]’ – specify dimension (dimension specification not supported in editing UI)
    • caption – caption to display below the image

Datetime

When formatting objects for reading by Haplo, for convenience simple dates can be encoded as strings in the XML. The dates are encoded in ISO 8601 format, YYYY-MM-DDThh:mm:ss, as the TEXT child of the a element. Objects will never be encoded in this simplified format.

Specified precision date ranges are encoded in XML as:

  • datetime
    • precision – precision of the date and time
      • TEXT – ‘C’ = century, ‘D’ = decade, ‘Y’ = year, ‘d’ = day, ‘h’ = hour, ‘m’ = minute
    • timezone ? – optional time zone, processed as GMT if not included
      • TEXT – one of the standard time zone names
    • start – start of the date and time range
      • TEXT – the date and time as YYYY-MM-DDThh:mm:ss, regardless of precision. This is ignored when reading objects.
      • year – year, as a number -4712 to 294275
      • month ? – month, as a number 1 to 12, if required by the precision
      • day ? – day, as a number 1 to 31, if required by the precision
      • hour ? – hour, as a number 0 to 23, if required by the precision
      • minute ? – minute, as a number 0 to 59, if required by the precision
    • end ? – optional end time of the range
      • (attributes and text as for start)

A simple date might be encoded as:

<datetime>
  <precision>d</precision>
  <start year="2009" month="8" day="12">2009-08-12T00:00:00</start>
</datetime>

Note that the string encoded date, 2009-08-12T00:00:00, is only included for convenience and will be ignored when this value is read.

Telephone numbers

  • telephone_number
    • country
      • TEXT – ISO country code
    • number
      • TEXT – telephone number as entered by the user, without the reformatting for display
    • intl_form
      • TEXT – number reformatted into international form, with local formatting. (ignored when importing)
    • extension ?
      • TEXT – extension number

The above format is strict, and requires correct country codes for Haplo to handle the data correctly. However, data is not always available in this form. When reading XML, Haplo also supports this form:

  • telephone_number
    • guess_country
      • TEXT – ISO country code (eg ‘GB’, ‘US’) of the country where this data was collected (not the country of the telephone number)
    • guess_from
      • TEXT – telephone number in whatever format is available
    • extension ?
      • TEXT – extension number (optional, will override any extension found in guess_from)

Data will be converted on reading to a best guess for the country code and local number. guess_country should be set to the country the data originated from. For example, even if the number is a US number, you should set guess_country to GB if the data was collected in England.

If you find any inputs which give bad results, please send them to Haplo Support so we can improve the guessing algorithm.

Postal addresses

  • postal_address
    • street1 ?
      • TEXT
    • street2 ?
      • TEXT
    • city ?
      • TEXT
    • county ?
      • TEXT
    • postcode ?
      • TEXT
    • country ?
      • TEXT – ISO code

NOTE: The country field must be a valid ISO code. If any other data is sent, for example, the country name as text, the server will reject the object.

URL

  • url
    • TEXT – URL

Person’s name

  • person_name
    • culture – ‘western’, ‘western_list’ or ‘eastern’
    • first ?
      • TEXT – first name
    • last ?
      • TEXT – last name
    • title ?
      • TEXT – title (eg ‘Mr’)
    • middle ?
      • TEXT – middle name / initials
    • suffix ?
      • TEXT – suffix (eg ‘III’ (“the third”) or ‘PhD’ (postnominals))

File reference

  • file_reference
    • file
      • TEXT – file identifier
    • secret
      • TEXT – file secret
    • filename
      • TEXT – filename for presentation to the user
    • mime_type
      • TEXT – MIME type of the file

File references include secrets to make identifiers non-guessable for security reasons. Obtain file references by uploading new files (see below) or copying from an existing object.

The system supports referring to the same file from two different objects, but this is not encouraged as it may lead to user confusion.

Example

<object ref="88y4w"
        created_user="20" updated="2008-10-30T14:38:33+00:00"
        updated_user="20" created="2008-10-30T14:38:33+00:00">
  <attributes>
    <a d="x3" vt="35">
      <person_name culture="western">
        <last>Bloggs</last>
        <first>Joe</first>
      </person_name>
    </a>
    <a d="x2" vt="0">20x1</a>
    <a d="259" vt="0">88y4q</a>
    <a d="193" vt="16">
      <text default="true" lang="en">Developer</text>
    </a>
    <a d="191" vt="29">
      <text>joe@example.com</text>
    </a>
    <a d="195" vt="32">
      <telephone_number>
        <country>GB</country>
        <number>020 1234 5678</number>
        <intl_form>+44 20 1234 5678</intl_form>
      </telephone_number>
    </a>
    <a d="195" q="76x" vt="32">
      <telephone_number>
        <country>GB</country>
        <number>07777 123 456</number>
        <intl_form>+44 7777 123456</intl_form>
      </telephone_number>
    </a>
    <a d="194" vt="36">
      <postal_address>
        <street1>1 High Street</street1>
        <city>Some City</city>
        <county>Anywhere</county>
        <postcode>XX1 2YY</postcode>
        <country>GB</country>
      </postal_address>
    </a>
    <a d="x5" vt="0">8ww43</a>
    <a d="25v" vt="0">88293</a>
    <a d="9w5" vt="24">
      <text default="true" lang="en">Some example text.
Includes line breaks.</text>
    </a>
    <a d="190" vt="30">
      <url>http://www.example.com</url>
    </a>
  </attributes>
</object>