SOAP defines types corresponding to the following
structural patterns often found in programming languages:
SOAP also permits serialization of data that is neither a
Struct nor an Array, for example data such as is found in a
Directed-Labeled-Graph Data Model in which a single node has
many distinct accessors, some of which occur more than
once. SOAP serialization does not require that the underlying
data model make an ordering distinction among accessors, but
if such an order exists, the accessors MUST be encoded in that
sequence.
4.4.1 Compound Values and References to Values
The members of a Compound Value are encoded as accessor
elements. When accessors are distinguished by their name (as
for example in a struct), the accessor name is used as the
element name. Accessors whose names are local to their
containing types have unqualified element names; all others
have qualified names.
The following is an example of a struct of type "Book":
Example: Book structure
<e:Book xmlns:e="http://example.org/2001/06/books" >
<author>Henry Ford</author>
<preface>Prefactory text</preface>
<intro>This is a book.</intro>
</e:Book>
And this is a schema fragment describing the above structure:
Example: Schema for Book structure
<xs:element name="Book"
xmlns:xs='http://www.w3.org/2001/XMLSchema' >
<xs:complexType>
<xs:sequence>
<xs:element name="author" type="xs:string" />
<xs:element name="preface" type="xs:string" />
<xs:element name="intro" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
Below is an example of a type with both simple and
complex members. It shows two levels of referencing. Note
that the href attribute of the Author
accessor element is a reference to the value whose
id attribute matches. A similar construction
appears for the Address accessor element.
Example: Book with muli-reference addresses
<e:Book xmlns:e="http://example.org/2001/06/books" >
<title>My Life and Work</title>
<author href="#Person-1"/>
</e:Book>
<e:Person xmlns:e="http://example.org/2001/06/books"
id="Person-1" >
<name>Henry Ford</name>
<address href="#Address-2"/>
</e:Person>
<e:Address xmlns:e="http://example.org/2001/06/books"
id="Address-2" >
<email>mailto:henryford@hotmail.com</email>
<web>http://www.henryford.com</web>
</e:Address>
The form above is appropriate when the "Person" value and
the "Address" value are multi-reference. If these were
instead both single-reference, they SHOULD be embedded, as
follows:
Example: Book with single-reference addresses
<e:Book xmlns:e="http://example.org/2001/06/books" >
<title>My Life and Work</title>
<author>
<name>Henry Ford</name>
<address>
<email>mailto:henryford@hotmail.com</email>
<web>http://www.henryford.com</web>
</address>
</author>
</e:Book>
If instead there existed a restriction that no two
persons can have the same address in a given instance and
that an address can be either a Street-address or an
Electronic-address, a Book with two authors would be encoded
as follows:
Example: Book with two authors having different addresses
<e:Book xmlns:e="http://example.org/2001/06/books" >
<title>My Life and Work</title>
<firstauthor href="#Person-1"/>
<secondauthor href="#Person-2"/>
</e:Book>
<e:Person xmlns:e="http://example.org/2001/06/books"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="Person-1" >
<name>Henry Ford</name>
<address xsi:type="e:ElectronicAddressType">
<email>mailto:henryford@hotmail.com</email>
<web>http://www.henryford.com</web>
</address>
</e:Person>
<e:Person xmlns:e="http://example.org/2001/06/books"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="Person-2">
<name>Samuel Crowther</name>
<address xsi:type="e:StreetAddressType">
<street>Martin Luther King Rd</street>
<city>Raleigh</city>
<state>North Carolina</state>
</address>
</e:Person>
Serializations can contain references to values not in the same
resource:
Example: Book with external references
<e:Book xmlns:e="http://example.org/2001/06/books" >
<title>Paradise Lost</title>
<firstAuthor href="http://www.dartmouth.edu/~milton/" />
</e:Book>
And this is a schema fragment describing the above structures:
Example: Schema for preceding example
<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://example.org/2001/06/books"
targetNamespace="http://example.org/2001/06/books" >
<xs:element name="Book" type="tns:BookType" />
<xs:complexType name="BookType" >
<xs:annotation>
<xs:documentation>
<info>
Either the following group must occur or else the
href attribute must appear, but not both.
</info>
</xs:documentation>
</xs:annotation>
<xs:sequence minOccurs="0" maxOccurs="1" >
<xs:element name="title" type="xs:string" />
<xs:element name="firstAuthor" type="tns:PersonType" />
<xs:element name="secondAuthor" type="tns:PersonType" />
</xs:sequence>
<xs:attribute name="href" type="xs:anyURI" />
<xs:attribute name="id" type="xs:ID" />
<xs:anyAttribute namespace="##other" />
</xs:complexType>
<xs:element name="Person" type="tns:PersonType" />
<xs:complexType name="PersonType" >
<xs:annotation>
<xs:documentation>
<info>
Either the following group must occur or else the
href attribute must appear, but not both.
</info>
</xs:documentation>
</xs:annotation>
<xs:sequence minOccurs="0" maxOccurs="1" >
<xs:element name="name" type="xs:string" />
<xs:element name="address" type="tns:AddressType" />
</xs:sequence>
<xs:attribute name="href" type="xs:anyURI" />
<xs:attribute name="id" type="xs:ID" />
<xs:anyAttribute namespace="##other" />
</xs:complexType>
<xs:element name="Address" base="tns:AddressType" />
<xs:complexType name="AddressType" abstract="true" >
<xs:annotation>
<xs:documentation>
<info>
Either one of the following sequences must occur or
else the href attribute must appear, but not both.
</info>
</xs:documentation>
</xs:annotation>
<xs:choice>
<xs:sequence minOccurs="0" maxOccurs="1" >
<xs:element name="email" type="xs:string" />
<xs:element name="web" type="xs:anyURI" />
</xs:sequence>
<xs:sequence minOccurs='0' maxOccurs='1' >
<xs:element name="street" type="xs:string" />
<xs:element name="city" type="xs:string" />
<xs:element name="state" type="xs:string"/>
</xs:sequence>
</xs:choice>
<xs:attribute name="href" type="xs:anyURI"/>
<xs:attribute name="id" type="xs:ID"/>
<xs:anyAttribute namespace="##other"/>
</xs:complexType>
<xs:complexType name="StreetAddressType">
<xs:annotation>
<xs:documentation>
<info>
Either the second sequence in the following group
must occur or else the href attribute must appear,
but not both.
</info>
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:restriction base="tns:AddressType" >
<xs:sequence>
<xs:sequence minOccurs="0" maxOccurs="0" >
<xs:element name="email" type="xs:string" />
<xs:element name="web" type="xs:anyURI" />
</xs:sequence>
<xs:sequence minOccurs="0" maxOccurs="1">
<xs:element name="street" type="xs:string" />
<xs:element name="city" type="xs:string" />
<xs:element name="state" type="xs:string"/>
</xs:sequence>
</xs:sequence>
<xs:attribute name="href" type="xs:anyURI"/>
<xs:attribute name="id" type="xs:ID"/>
<xs:anyAttribute namespace="##other"/>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="ElectronicAddressType">
<xs:annotation>
<xs:documentation>
<info>
Either the first sequence in the following group
must occur or else the href attribute must appear,
but not both.
</info>
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:restriction base="tns:AddressType" >
<xs:sequence>
<xs:sequence minOccurs="0" maxOccurs="1">
<xs:element name="email" type="xs:string" />
<xs:element name="web" type="xs:anyURI" />
</xs:sequence>
<xs:sequence minOccurs="0" maxOccurs="0">
<xs:element name="street" type="xs:string" />
<xs:element name="city" type="xs:string" />
<xs:element name="state" type="xs:string"/>
</xs:sequence>
</xs:sequence>
<xs:attribute name="href" type="xs:anyURI"/>
<xs:attribute name="id" type="xs:ID"/>
<xs:anyAttribute namespace="##other"/>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
</xs:schema>
4.4.2 Arrays
SOAP arrays are defined as having a type of enc:Array or
a derived type having that type in its derivation hierarchy
(see also rule 8 in 4.1 Rules for Encoding Types in XML). Such
derived types would be restrictions of the enc:Array type
and could be used to represent, for example, arrays limited
to integers or arrays of some user-defined
enumeration. Arrays are represented as element values, with
no specific constraint on the name of the containing element
(just as values generally do not constrain the name of their
containing element). The elements which make up the array
can themselves can be of any type, including nested
arrays.
The representation of the value of an array is an ordered
sequence of elements constituting the items of the
array. Within an array value, element names are not
significant for distinguishing accessors. Elements may have
any name. In practice, elements will frequently be named so
that their declaration in a schema suggests or determines
their type. As with compound types generally, if the value
of an item in the array is a single-reference value, the
item contains its value. Otherwise, the item references its
value via an href attribute.
The following example is a schema fragment and an array
containing integer array members:
Example: Schema declaring an array of integers
<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding" >
<xs:import namespace="http://www.w3.org/2001/12/soap-encoding" />
<xs:element name="myFavoriteNumbers" type="enc:Array" />
</xs:schema>
Example: Array conforming to the preceding schema
<myFavoriteNumbers xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
enc:arrayType="xs:int[2]" >
<number>3</number>
<number>4</number>
</myFavoriteNumbers>
In the preceding example, the array myFavoriteNumbers
contains several members each of which is a value of type
xs:int. This can be determined by inspection of the
enc:arrayType attribute. Note that the enc:Array
type allows both unqualified element names and qualified
element names from any namespace. These convey no type
information, so when used they must either have an
xsi:type attribute or the containing element must
have a enc:arrayType attribute. Naturally, types
derived from enc:Array may declare local elements, with type
information.
As previously noted, the enc schema contains declarations
of elements with names corresponding to each simple type in
the "XML Schema Part 2: Datatypes" Specification[5]. It also contains a declaration for
Array . They are used in the following example:
Example: Using the enc:Array element
<enc:Array xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
enc:ArrayType="xs:int[2]" >
<enc:int>3</enc:int>
<enc:int>4</enc:int>
</enc:Array>
Arrays can contain instances of any subtype of the
specified arrayType. That is, the members may be of any
type that is substitutable for the type specified in the
arrayType attribute, according to whatever
substitutability rules are expressed in the schema. So, for
example, an array of integers can contain any type derived
from integer (for example "int" or any user-defined
derivation of integer). Similarly, an array of "address"
might contain a restricted or extended type such as
"internationalAddress". Because the supplied
enc:Array type admits members of any type,
arbitrary mixtures of types can be contained unless
specifically limited by use of the arrayType
attribute.
Types of member elements can be specified using the
xsi:type attribute in the instance, or by
declarations in the schema of the member elements, as the
following two arrays demonstrate respectively:
Example: Array with elements of varying types
<enc:Array xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xs:anyType[4]">
<thing xsi:type="xs:int">12345</thing>
<thing xsi:type="xs:decimal">6.789</thing>
<thing xsi:type="xs:string">
Of Mans First Disobedience, and the Fruit
Of that Forbidden Tree, whose mortal tast
Brought Death into the World, and all our woe,
</thing>
<thing xsi:type="xs:anyURI">
http://www.dartmouth.edu/~milton/reading_room/
</thing>
</enc:Array>
Example: Array with elements of varying types
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
enc:arrayType="xs:anyType[4]" >
<enc:int>12345</enc:int>
<enc:decimal>6.789</enc:decimal>
<enc:string>
Of Mans First Disobedience, and the Fruit
Of that Forbidden Tree, whose mortal tast
Brought Death into the World, and all our woe,
</enc:string>
<enc:anyURI>
http://www.dartmouth.edu/~milton/reading_room/
</enc:anyURI >
</enc:Array>
Array values may be structs or other compound values. For
example an array of "xyz:Order" structs :
Example: Arrays containing structs and other compound values
<enc:Array xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:xyz="http://example.org/2001/06/Orders"
enc:arrayType="xyz:Order[2]">
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</enc:Array>
Arrays may have other arrays as member values. The
following is an example of an array of two arrays, each of
which is an array of strings.
Example: Array containing other arrays
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
enc:arrayType="xs:string[][2]" >
<item href="#array-1"/>
<item href="#array-2"/>
</enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
id="array-1"
enc:arrayType="xs:string[3]">
<item>r1c1</item>
<item>r1c2</item>
<item>r1c3</item>
</enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
id="array-2"
enc:arrayType="xs:string[2]">
<item>r2c1</item>
<item>r2c2</item>
</enc:Array>
The element containing an array value does not need to be
named "enc:Array". It may have any name, provided that the
type of the element is either enc:Array or is derived from
enc:Array by restriction. For example, the following is a
fragment of a schema and a conforming instance array:
Example: Schema for an array
<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:tns="http://example.org/2001/06/numbers"
targetNamespace="http://example.org/2001/06/numbers" >
<xs:simpleType name="phoneNumberType" >
<xs:restriction base="xs:string" />
</xs:simpleType>
<xs:element name="ArrayOfPhoneNumbers" type="tns:ArrayOfPhoneNumbersType" />
<xs:complexType name="ArrayOfPhoneNumbersType" >
<xs:complexContent>
<xs:restriction base="enc:Array" >
<xs:sequence>
<xs:element name="phoneNumber" type="tns:phoneNumberType" maxOccurs="unbounded" />
</xs:sequence>
<xs:attributeGroup ref="enc:arrayAttributes" />
<xs:attributeGroup ref="enc:commonAttributes" />
</xs:restriction>
</xs:complexContent>
</xs:complexType>
</xs:schema>
Example: Array conforming to the preceding schema
<abc:ArrayOfPhoneNumbers xmlns:abc="http://example.org/2001/06/numbers"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
enc:arrayType="abc:phoneNumberType[2]" >
<phoneNumber>206-555-1212</phoneNumber>
<phoneNumber>1-888-123-4567</phoneNumber>
</abc:ArrayOfPhoneNumbers>
Arrays may be multi-dimensional. In this case, more than
one size will appear within the asize part of the
arrayType attribute:
Example: Multi-dimensonal array
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
enc:arrayType="xs:string[2,3]" >
<item>r1c1</item>
<item>r1c2</item>
<item>r1c3</item>
<item>r2c1</item>
<item>r2c2</item>
<item>r2c3</item>
</enc:Array>
While the examples above have shown arrays encoded
by reference, array values SHOULD appear embedded.
The following is an example of a schema fragment and an
array of phone numbers embedded in a struct of type "Person"
and accessed through the accessor "phoneNumbers":
Example: Schema fragment for array of phone numbers embedded in a struct
<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:tns="http://example.org/2001/06/numbers"
targetNamespace="http://example.org/2001/06/numbers" >
<xs:import namespace="http://www.w3.org/2001/12/soap-encoding" />
<xs:simpleType name="phoneNumberType" >
<xs:restriction base="xs:string" />
</xs:simpleType>
<xs:element name="ArrayOfPhoneNumbers" type="tns:ArrayOfPhoneNumbersType" />
<xs:complexType name="ArrayOfPhoneNumbersType" >
<xs:complexContent>
<xs:restriction base="enc:Array" >
<xs:sequence>
<xs:element name="phoneNumber" type="tns:phoneNumberType" maxOccurs="unbounded" />
</xs:sequence>
<xs:attributeGroup ref="enc:arrayAttributes" />
<xs:attributeGroup ref="enc:commonAttributes" />
</xs:restriction>
</xs:complexContent>
</xs:complexType>
<xs:element name="Person">
<xs:complexType>
<xs:sequence>
<xs:element name="name" type="xs:string" />
<xs:element name="phoneNumbers" type="tns:ArrayOfPhoneNumbersType" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Example: Array of phone numbers embedded in a struct conforming to the preceding schema
<def:Person xmlns:def="http://example.org/2001/06/numbers"
xmlns:enc="http://www.w3.org/2001/12/soap-encoding" >
<name>John Hancock</name>
<phoneNumbers enc:arrayType="def:phoneNumber[2]">
<phoneNumber>206-555-1212</phoneNumber>
<phoneNumber>1-888-123-4567</phoneNumber>
</phoneNumbers>
</def:Person>
Here is another example of a single-reference array value
encoded as an embedded element whose containing element name
is the accessor name:
Example: Single-reference array encoded as en embedded element
<xyz:PurchaseOrder xmlns:xyz="http://example.org/2001/06/Orders" >
<CustomerName>Henry Ford</CustomerName>
<ShipTo>
<Street>5th Ave</Street>
<City>New York</City>
<State>NY</State>
<Zip>10010</Zip>
</ShipTo>
<PurchaseLineItems xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
enc:arrayType="xyz:Order[2]">
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</PurchaseLineItems>
</xyz:PurchaseOrder>
4.4.2.1 PartiallyTransmitted Arrays
SOAP provides support for partially transmitted arrays,
known as "varying" arrays in some contexts[5]. A partially transmitted array
indicates in an enc:offset attribute the zero-origin
offset of the first element transmitted. If omitted, the
offset is taken as zero.
The following is an example of an array of size five
that transmits only the third and fourth element counting
from zero:
Example: Array of size five that transmits only the third and fourth element
<enc:Array xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
enc:arrayType="xs:string[6]"
enc:offset="[3]" >
<item>The fourth element</item>
<item>The fifth element</item>
</enc:Array>
4.4.2.2 SparseArrays
SOAP provides support for sparse arrays. Each element
representing a member value contains a enc:position
attribute that indicates its position within the
array. The following is an example of a sparse array of
two-dimensional arrays of strings. The size is 4 but only
position 2 is used:
Example: Sparse array
<enc:Array xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
enc:arrayType="xs:string[,][4]" >
<enc:Array href="#array-1" enc:position="[2]" />
</enc:Array>
<enc:Array id="array-1"
enc:arrayType="xs:string[10,10]" >
<item enc:position="[2,2]">Third row, third col</item>
<item enc:position="[7,2]">Eighth row, third col</item>
</enc:Array>
If the only reference to "array-1"
occurs in the enclosing array, this example could also
have been encoded as follows:
Example: Alternative serialisation
<enc:Array xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
enc:arrayType="xs:string[,][4]" >
<enc:Array enc:position="[2]" enc:arrayType="xs:string[10,10]" > <item enc:position="[2,2]">Third row, third col</item>
<item enc:position="[7,2]">Eighth row, third col</item>
</enc:Array>
</enc:Array>
4.4.3 Generic Compound Types
The encoding rules just cited are not limited to those
cases where the accessor names are known in advance. If
accessor names are known only by inspection of the immediate
values to be encoded, the same rules apply, namely that the
accessor is encoded as an element whose name matches the
name of the accessor, and the accessor either contains or
references its value. Accessors containing values whose
types cannot be determined in advance MUST always contain an
appropriate xsi:type attribute giving the type of
the value.
Similarly, the rules cited are sufficient to allow
serialization of compound types having a mixture of
accessors distinguished by name and accessors distinguished
by both name and ordinal position. (That is, having some
accessors repeated.) This does not require that any schema
actually contain such types, but rather says that if a
type-model schema does have such types, a corresponding XML
syntactic schema and instance may be generated.
Example: Generic compound types
<xyz:PurchaseOrder xmlns:xyz="http://example.org/2001/06/Orders" >
<CustomerName>Henry Ford</CustomerName>
<ShipTo>
<Street>5th Ave</Street>
<City>New York</City>
<State>NY</State>
<Zip>10010</Zip>
</ShipTo>
<PurchaseLineItems>
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</PurchaseLineItems>
</xyz:PurchaseOrder>
Similarly, it is valid to serialize a compound value that
structurally resembles an array but is not of type (or
subtype) enc:Array. For example:
Example: Compound value
<PurchaseLineItems>
<Order>
<Product>Apple</Product>
<Price>1.56</Price>
</Order>
<Order>
<Product>Peach</Product>
<Price>1.48</Price>
</Order>
</PurchaseLineItems>
