Abstract

The Navajo Document model was introduced to create a language with certain semantic features to communicate with web services. A Navajo Document is used to communicate with business oriented services in the spirit of a true Service Oriented Architecture that is loosely coupled and does not have to deal with a shared domain model between the applications. It is based on the request/response paradigm of the web. It proposes a single language, in comparison to the typical XML Schema approach for defining a new language for each new web service. The Navajo Document model combines data and meta data (simple semantics). The original main purpose of the semantic features was to be able to generate a feature rich user interface for any Navajo Document instance. The first generic 'client' used a simple XSLT script to generate a fully functional HTML user interface with which an entire Service Based application could be used without hand coding any user interface.

This specification defines the Navajo Document Model using its default serialization, XML. Furthermore, the document defines an API for the Navajo Document Model that can be implemented in any programming language, like Java, C#, Objective C, PHP.

Table of Contents

• 1. Introduction
• 2. The Basic Elements
• 3. Property
  • 3.1. Types
  • 3.2. Selection property
• 4. Message
  • 4.1. Array message
  • 4.2. Array message with header definition
• 5. Methods
• 6. Header
• 7. Navajo Path Expression
• 8. The Navajo Document API
  • 8.1. Navajo
  • 8.2. Header
  • 8.3. Message
  • 8.4. Property
  • 8.5. Selection
  • 8.6. Method

Appendices

• A Navajo Document XSD
• B Navajo Document OWL ontology

1. Introduction

This document describes the specification of the Navajo Document Model or shorthand Navajo Document. Navajo Document is used to model request and response of (Navajo) Web Services using the concept of 'Forms'. The default Navajo Document serialization structure is XML. In this documentation we will the XML representation to explain the Navajo Document Model. Navajo Document is specifically suited for augmenting various data elements with meta data like type and subtype and description. Furthermore, the simplicity of the XML structure enables the use of an easy to use variant of the XPath expression language.

Using Navajo Document you can:

• Specify request and response structure for Web Services much like HTML documents but without specifying layout
• Use various data types like string, integer, boolean, etc. but also a powerful binary datatype
• Specify repetitive complex data structures
• Specify subsequent web services that can be called using the current Navajo Document instance as input

A generated user interface is shown and (part of) its corresponding Navajo Document.

Fig. 1	Fig. 2

2. The Basic Elements

The Navajo Document Model consists of the following XML elements:

• a property element to model any data. A property can have meta data like type information, a description, the (max) data length, whether it is read-only or writable.
• a message for defining complex data types. A message simply groups property elements. Repetitive structures can be defined using an 'array' type message.
• an option element to model selection type of data (e.g. for dropdown boxes and selection lists).
• a methods/method elements to model defines subsequent web services that can be called using the current Navajo Document.
• a header element to specify a web service request.
• a tml, the top level element.

Example The following example shows an Navajo Document as XML (as shown in Fig. 2):

<tml>
   <header>
      <transaction rpc_usr="joe" rpc_name="GetClubDetails" rpc_pwd="secret"/>
   <header>
   <message name="BVODetails" type="simple">
      <property description="Organization Name" direction="in" name="Name" value="Fortuna Sittard" length="" type="string"/>
      <property description="Start date" direction="in" name="StartDate" value="2009-07-15 10:03:12.444" length="" type="date"/>
      <property description="Type of organization" direction="in" name="OrganizationType" length="" type="selection" cardinality="+">
         <option selected="1" name="SportClub" value="Sports club"/>
         <option selected="0" name="Facility" value="Sports facility"/>
         <option selected="0" name="SportStore" value="Sports store"/>
         <option selected="0" name="SportsFederation" value="Sports federation"/>
      <property>
      <property description="Logo" direction="out" subtype="extension=jpg,handle=binary_object562366navajo,mime=image/jpeg" name="Logo" length="46080" type="binary">
/9j/4AAQSkZJRgABAgEASABIAAD/4RpwRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUA
AAABAAAAYgEbAAUAAAABAAAAagEoAAMAAAABAAIAAAExAAIAAAAdAAAAcgEyAAIAAAAUAAAAj4dp
    [...]
 </tml>

3. Property

All data in a Navajo Document is represented as properties. Properties are defined using the property tag. A property can have the following attributes:

• name, the name of the property. A property name must be unique within the scope of a message and it is mandatory.
• value, contains the value of the data element. The value attribute is mandatory. A value is defined as a string but it is constrained by the type information. A value can also be represented as a text node of a property tag.
• type, contains the type of the data element. Valid types are specified in section 3.1. The type attribute is mandatory.
• subtype, subtype contains key/value options for additional type constraints like formatting, valid data ranges, mime-type, etc. The subtype information CAN be used by a client for proper rendering. The subtype attribute is optional
• description, additional subscription for the property. The description attribute is optional
• direction, valid direction options are "in" or "out". The value "out" specifies that the property is read-only. It is basically a 'hint' for the client side. The direction attribute is optional.
• length, additional maximum length hint for the property value. The length attribute is optional

3.1 Types

Types can be specified within the type attribute of a property. The Navajo Document Model defines a number of different types:

• string, a default string datatype.
• date, a date datatype. Since all property values are represented as strings, the following format must be used for date types: yyyy-MM-dd (the ISO 8601 Calendar date representation). For example, 1971-06-17 is a valid date.
• boolean, a boolean datatype. The only valid values are "true" and "false".
• float, for representing any floating point number. The precision is not specified, all broken numbers should be serialized using a dot (.) as a decimal separator.
• integer, for representing any integer number.
• clocktime, for representing clock times (24 hour clock). The format for representing clock times is HH:mm:ss (in Java SimpleDateFormat format).
• binary, for representing binary data. Binary data must be represented using Base64 encoding (see RFC 2045).
• selection, for representing key/value data (see Selection property).

3.2 Selection property

A special type of property is the so called 'selection property'. A selection property can be used to model simple key/value pairs that are typically represented in user interfaces like dropdown lists, selection lists or radio button groups. A property of type 'selection' must have an additional attribute: cardinality. The cardinality of selection property specifies whether a single key/value pair (cardinality="1") or multiple (cardinality="+") key/value pairs may be selected.

NOTE that the names used in this section might be misleading. This is due to legacy and backwards compatibility; the Navajo Document model and its use within the Navajo Service Oriented Framework has evolved since 2002. Actually, the option tag name is called a Selection in the corresponding Navajo Document API! Also the key/value pairs are called name/value pairs in the current version of the Navajo Document Model.

Key/value pairs are modeled using the option tag. An option tag must have the following attributes:

• name, the key.
• value, the value.
• selected, specifies whether the option is selected (1) or not (0).

Example

  <property name="Choose" type="selection" cardinality="1" direction="in">
     <option name="Good" value="3" selected="0">
     <option name="Better" value="2" selected="0">
     <option name="Best" value="1" selected="1">
  <property>

4. Message

All properties must be grouped within messages. A message can be nested, i.e. it may have a parent message. Messages are defined using the message tag. A message can have the following attributes:

• name, the name of the message. The name must be unique between its siblings (message at the same level). The name attribute is mandatory.
• type, an additional type attribute. Valid types are 'simple', 'array' and 'definition'. The type element is optional and defaults to 'simple'.
• index, an optional attribute used within the context of array type messages.

4.1 Array message

An array message, i.e. a message with type 'array' is used to model a set of complex data, i.e. group of properties and/or messages. An array message consists of a top level array message, defining its name:

<message name="MyArrayMessage" type="array"/>

Example

<message name="MyArrayMessage" type="array">
   <message name="MyArrayMessage">
     <property name="Identification" type="string" length="64" description="Unique identifier for this entity" value="A1"/>
     <property name="RegistrationDate" type="date" value="1978-01-01"/>
   <message>
   <message name="MyArrayMessage">
     <property name="Identification" type="string" length="64" description="Unique identifier for this entity" value="C2"/>
     <property name="RegistrationDate" type="date" value="2003-06-09"/>
   <message>
   <message name="MyArrayMessage">
     <property name="Identification" type="string" length="64" description="Unique identifier for this entity" value="F9"/>
     <property name="RegistrationDate" type="date" value="1999-03-21"/>
   <message>
<message>

4.2 Array message with header definition

Sometimes it can be convenient, for the sake of bandwidth reduction, to specify the 'structure' of an array message only once instead of repeating property attributes for each array sub message. This can be accomplished by defining a special sub message as the first element of the array message using a special message type called 'definition'.

Example

  <message name="MyArrayMessage" type="array">
   <message name="MyArrayMessage" type="definition">
     <property name="Identification" type="string" length="64" description="Unique identifier for this entity"/>
     <property name="RegistrationDate" type="date"/>
   <message>
   <message name="MyArrayMessage">
     <property name="Identification" value="A1"/>
     <property name="RegistrationDate" value="1978-01-01"/>
   <message>
   <message name="MyArrayMessage">
     <property name="Identification" value="C2"/>
     <property name="RegistrationDate" value="2003-06-09"/>
   <message>
   <message name="MyArrayMessage">
     <property name="Identification" value="F9"/>
     <property name="RegistrationDate" value="1999-03-21"/>
   <message>
<message> 

5. Methods

The main purpose of the Navajo Document Model is to be a communication language with (and between) web services. A Navajo Document serves as input (request) as well as output (response) for a web service. Complex tasks are typically composed of multiple web services that are called in a certain sequence. A well known 'call pattern' is e.g. calling a web service that queries data about some entity, modifying some values and calling a subsequent web service that stores the modified data. The web service interaction pattern may be specified in the Navajo Document to serve as an additional 'hint' for web service clients.

A Navajo Document may specify zero or more subsequent web services that use the current Navajo Document instance as input. These web services are modeled using the methods tag that contains method children tags to specify each web service. The name of the web service is defined in a mandatory name attribute. Example

<methods>
  <method name="StoreBook"/>
  <method name="DeleteBook"/>
<methods>

6. Header

A Navajo Document instance contains AT MOST 1 header element. The header element is used to define web service related information, i.e. information that can be used by some web service server provider to identify the user (client) that is calling a web service.

A header contains AT MOST a single transaction element that has the following mandatory attributes:

• rpc_name, to indicate the web service that the client wants to use.
• rpc_usr and rpc_pwd as a basic method for client authentication. It depends on the Navajo server implementation how these values are treated.

  <header>
    <transaction rpc_usr="joe" rpc_pwd="mysecret" rpc_name="ShowMe"/>
  </header>

• ref, contains the unique reference to the server thread as specified by the server. This ref should be present in subsequent polling requests.
• perc_ready, contains an optional value indicating the execution progress of the remote thread as given by the server.
• name, contains a readable name for the remote thread as given by the server.
• finished, whether or not the remote thread as finished its work.
• interrupt, the only attribute that can be modified by the client. It is used to control the remote thread by giving the client a possibility to give 'commands' that a web service server may or may not respect. The commands are: interrupt, resume or kill to respectively stop, restart or kill the remote thread.

 <header>
    <transaction rpc_usr="joe" rpc_pwd="mysecret" rpc_name="SomeAsyncService"/>
    <callback>
            <object perc_ready="0.0" ref="8532343" name="async" finished="false" interrupt=""/>
    <callback>
 </header>

7. Navajo Path Expression

Navajo messages and properties can be addresses by using XPath expressions. However, since the Navajo Document Models defines a very strict structure, a much simpler addressing method can be applied.

Messages are addressed either absolutely (using / prefix) or relatively (using ../ or no prefixes):

  MessageName := [:string]('@'[:integer]){0,1}
  MessagePathExpression ::= ( '/'{0,1} | '../'*) MessageName ('/'|'../'MessageName)*

Properties must be addressed with a Message Path Expression prefix:

  PropertyName ::= [:string]
  PropertyPathExpression ::= MessagePathExpression'/'PropertyName

Consider the following Navajo Document instance:

 <tml>
   <message name="SomeMessage">
      <property name="FirstProperty" type="string" value="alphabetagamma"/>
      <message name="MyArrayMessage" type="array">
         <message name="MyArrayMessage" index="0">
           <property name="Identification" type="string" length="64" description="Unique identifier for this entity" value="A1"/>
           <property name="RegistrationDate" type="date" value="1978-01-01"/>
         <message>
         <message name="MyArrayMessage" index="1">
           <property name="Identification" type="string" length="64" description="Unique identifier for this entity" value="C2"/>
           <property name="RegistrationDate" type="date" value="2003-06-09"/>
         <message>
      <message>
   </message> 
 </tml>

  /SomeMessage (name) = 'SomeMessage' 
  /SomeMessage/FirstProperty (value) = 'alphabetagamma'
  /SomeMessage/MyArrayMessage@1/RegistrationDate (value) = '2003-06-09'  
  /SomeMessage/MyArrayMessage@1/../FirstProperty (value)= 'alphabetagamma'

8. The Navajo Document API

The purpose of the Navajo Document API is to specify a standard for accessing, modifying and creating Navajo Document XML instances from any programming language. A set of classes is proposed and for each of the classes an interface is specified.

The following interface definitions are introduced:

• Navajo, the top level interface, i.e. holds everything from the tml tag.
• Header, represents the header element of a Navajo Document.
• Message, represents all message elements present in the Navajo Document.
• Property, represents all property elements in the Navajo Document.
• Selection, the selection property interface. Basically represents the option element of a selection property.
• Method, represents all method elements in a Navajo Document.

8.1 Navajo

The Navajo interface is the top level interface. Each Navajo Document instance has a corresponding Navajo object.

  interface Navajo {
      void addHeader(in Header)
      void addMessage(in Message, [Optional] in boolean overwrite)
      void addMethod(in Method)
      Navajo copy()
      list<Message> getAllMessages()
      list<Method> getAllMethods()
      Header getHeader()
      Message getMessage(in string name)
      Method getMethod(in string name)
      Property getProperty(in string name)
      boolean isEqual(Navajo)
  }

8.2 Header

An object implementing the Header interface corresponds to the header part of the Navajo Document Model.

  interface Header {
      void setRPCName(in string webservice)
      void setRPCPassword(in string password)
      void setRPCUser(in string username)
      string getRPCName()
      string getRPCPassword()
      string getRPCUser()
  }

8.3 Message

An object implementing the Message interface corresponds to a message element (including its sub messages) of a Navajo Document instance.

  interface Message {
      void setName(in string messagename)
      string getName()
      void setType(in 'simple'|'array'|'definition' type)
      'simple'|'array'|'definition' getType()
      void addMessage(in Message, [Optional] in boolean overwrite)     
      void addElement(in Message)     
      list<Message> getAllMessages()
      Message getMessage(in string name)
      Message getParentMessage()
      void addProperty(in Property)
      Property getProperty(in string name)
      list<Property> getAllProperties()
  }

8.4 Property

An object implementing the Property interface corresponds to a property element (including its sub messages) of a Navajo Document instance.

  interface Property {
     void setName(in string propertyname)
     string getName()
     void setValue(in object value)
     object getValue()
     void setLength(in integer length)
     integer getLength()
     void setType(in string type) 
     string getType()
     void setSubType(in string key, in string value) 
     string getSubType(in string key)
     string removeSubType(in string key)
     string getSubTypes()
     void setCardinality(in '1'|'+' cardinality) 
     string getCardinality()
     void setDirection(in 'in'|'out' direction) 
     'in'|'out' getDirection()
     void setDescription(in string description)
     string getDescription()
     void addSelection(in Selection)
     list<Selection> getAllSelectedSelections()
     list<Selection> getAllSelections()
  }

8.5 Selection

An object implementing the Selection interface corresponds to an option element of a Navajo Document instance.

  interface Selection {
     void setName(in string name)
     string getName()
     void setValue(in string value)
     string getValue()
     void setSelected(in boolean selected)
     boolean isSelected()
  }

8.6 Method

An object implementing the Method interface corresponds to an method element of a Navajo Document instance. If a Method object is added to a Navajo object, the methods tag should be created if none is present, otherwise it should be reused.

  interface Method {
     void setName(in string name)
     string getName()
  }

Appendix A: Navajo Document XSD

<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="tml">
        <xs:annotation>
            <xs:documentation>This is the top level tag</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element maxOccurs="1" minOccurs="1" ref="xtml:header"/>
                <xs:element maxOccurs="1" minOccurs="0" ref="xtml:methods"/>
                <xs:choice maxOccurs="unbounded" minOccurs="0">
                    <xs:element ref="xtml:message"/>
                </xs:choice>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="header">
        <xs:annotation>
            <xs:documentation>Contains the target Navajo service and username/password information</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="transaction"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="transaction">
        <xs:complexType>
            <xs:attribute name="rpc_name" type="xs:string" use="required"/>
            <xs:attribute name="rpc_usr" type="xs:string" use="required"/>
            <xs:attribute name="rpc_pwd" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="message">
        <xs:annotation>
            <xs:documentation>A message groups properties and other messages</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:choice>
                <xs:element maxOccurs="unbounded" ref="message"/>
                <xs:element maxOccurs="unbounded" ref="property"/>
            </xs:choice>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="type" type="xs:string"/>
            <xs:attribute name="index" type="xs:integer"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="property">
        <xs:annotation>
            <xs:documentation>A property is the basic data element</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element maxOccurs="unbounded" minOccurs="0" ref="option"/>
            </xs:sequence>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="type" use="required">
                <xs:simpleType>
                    <xs:restriction base="xs:NMTOKEN">
                        <xs:enumeration value="boolean"/>
                        <xs:enumeration value="integer"/>
                        <xs:enumeration value="selection"/>
                        <xs:enumeration value="string"/>
                        <xs:enumeration value="date"/>
                        <xs:enumeration value="float"/>
                        <xs:enumeration value="binary"/>
                        <xs:enumeration value="money"/>
                        <xs:enumeration value="clocktime"/>
                        <xs:enumeration value="stopwatchtime"/>
                        <xs:enumeration value="percentage"/>
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
            <xs:attribute name="value" type="xs:string"/>
            <xs:attribute name="direction" use="required">
                <xs:simpleType>
                    <xs:restriction base="xs:NMTOKEN">
                        <xs:enumeration value="in"/>
                        <xs:enumeration value="out"/>
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
            <xs:attribute name="length" type="xs:byte"/>
            <xs:attribute name="cardinality" type="xs:string"/>
            <xs:attribute name="description" type="xs:string"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="option">
        <xs:annotation>
            <xs:documentation>Used in properties of type selection to define a list of (possibly selected) name/value pairs</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="value" type="xs:string" use="required"/>
            <xs:attribute name="selected" use="required">
                <xs:simpleType>
                    <xs:restriction base="xs:NMTOKEN">
                        <xs:enumeration value="1"/>
                        <xs:enumeration value="0"/>
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
        </xs:complexType>
    </xs:element>
    <xs:element name="methods">
        <xs:annotation>
            <xs:documentation>Links to possible subsequent methods</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element maxOccurs="unbounded" ref="method"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="method">
        <xs:annotation>
            <xs:documentation>A method location</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="description" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
</xs:schema>

$Id: NavajoDocument.html,v 1.13 2009/07/15 16:31:56 arjen Exp $