5 SOAP Encoding

[Previous] [Next]

The SOAP encoding style is based on a simple type system that is a generalization of the common features found in type systems in programming languages, databases and semi-structured data. A type either is a simple (scalar) type or is a compound type constructed as a composite of several parts, each with a type. This is described in more detail below. This section defines rules for serialization of a graph of typed objects. It operates on two levels. First, given a schema in any notation consistent with the type system described, a schema for an XML grammar may be constructed. Second, given a type-system schema and a particular graph of values conforming to that schema, an XML instance may be constructed. In reverse, given an XML instance produced in accordance with these rules, and given also the original schema, a copy of the original value graph may be constructed.

The namespace identifier for the elements and attributes defined in this section is "http://schemas.xmlsoap.org/soap/encoding/". The encoding samples shown assume all namespace declarations are at a higher element level.

Use of the data model and encoding style described in this section is encouraged but not required; other data models and encodings can be used in conjunction with SOAP (see section 4.1.1).

5.1 Rules for Encoding Types in XML

XML allows very flexible encoding of data. SOAP defines a narrower set of rules for encoding. This section defines the encoding rules at a high level, and the next section describes the encoding rules for specific types when they require more detail. The encodings described in this section can be used in conjunction with the mapping of RPC calls and responses specified in Section 7.

To describe encoding, the following terminology is used:

1. A "value" is a string, the name of a measurement (number, date, enumeration, etc.) or a composite of several such primitive values. All values are of specific types.
2. A "simple value" is one without named parts. Examples of simple values are particular strings, integers, enumerated values etc.
3. A "compound value" is an aggregate of relations to other values. Examples of Compound Values are particular purchase orders, stock reports, street addresses, etc.
4. Within a compound value, each related value is potentially distinguished by a role name, ordinal or both. This is called its "accessor." Examples of compound values include particular Purchase Orders, Stock Reports etc. Arrays are also compound values. It is possible to have compound values with several accessors each named the same, as for example, RDF does.
5. An "array" is a compound value in which ordinal position serves as the only distinction among member values.
6. A "struct" is a compound value in which accessor name is the only distinction among member values, and no accessor has the same name as any other.
7. A "simple type" is a class of simple values. Examples of simple types are the classes called "string," "integer," enumeration classes, etc.
8. A "compound type" is a class of compound values. An example of a compound type is the class of purchase order values sharing the same accessors (shipTo, totalCost, etc.) though with potentially different values (and perhaps further constrained by limits on certain values).
9. Within a compound type, if an accessor has a name that is distinct within that type but is not distinct with respect to other types, that is, the name plus the type together are needed to make a unique identification, the name is called "locally scoped." If however the name is based in part on a Uniform Resource Identifier, directly or indirectly, such that the name alone is sufficient to uniquely identify the accessor irrespective of the type within which it appears, the name is called "universally scoped."
10. Given the information in the schema relative to which a graph of values is serialized, it is possible to determine that some values can only be related by a single instance of an accessor. For others, it is not possible to make this determination. If only one accessor can reference it, a value is considered "single-reference". If referenced by more than one, actually or potentially, it is "multi-reference." Note that it is possible for a certain value to be considered "single-reference" relative to one schema and "multi-reference" relative to another.
11. Syntactically, an element may be "independent" or "embedded." An independent element is any element appearing at the top level of a serialization. All others are embedded elements.

Although it is possible to use the xsi:type attribute such that a graph of values is self-describing both in its structure and the types of its values, the serialization rules permit that the types of values MAY be determinate only by reference to a schema. Such schemas MAY be in the notation described by "XML Schema Part 1: Structures" [10] and "XML Schema Part 2: Datatypes" [11] or MAY be in any other notation. Note also that, while the serialization rules apply to compound types other than arrays and structs, many schemas will contain only struct and array types.

The rules for serialization are as follows:

1. All values are represented as element content. A multi-reference value MUST be represented as the content of an independent element. A single-reference value SHOULD not be (but MAY be).
2. For each element containing a value, the type of the value MUST be represented by at least one of the following conditions: (a) the containing element instance contains an xsi:type attribute, (b) the containing element instance is itself contained within an element containing a (possibly defaulted) SOAP-ENC:arrayType attribute or (c) or the name of the element bears a definite relation to the type, that type then determinable from a schema.
3. A simple value is represented as character data, that is, without any subelements. Every simple value must have a type that is either listed in the XML Schemas Specification, part 2 [11] or whose source type is listed therein (see also section 5.2).
4. A Compound Value is encoded as a sequence of elements, each accessor represented by an embedded element whose name corresponds to the name of the accessor. Accessors whose names are local to their containing types have unqualified element names; all others have qualified names (see also section 5.4).
5. A multi-reference simple or compound value is encoded as an independent element containing a local, unqualified attribute named "id" and of type "ID" per the XML Specification [7]. Each accessor to this value is an empty element having a local, unqualified attribute named "href" and of type "uri-reference" per the XML Schema Specification [11], with a "href" attribute value of a URI fragment identifier referencing the corresponding independent element.
6. Strings and byte arrays are represented as multi-reference simple types, but special rules allow them to be represented efficiently for common cases (see also section 5.2.1 and 5.2.3). An accessor to a string or byte-array value MAY have an attribute named "id" and of type "ID" per the XML Specification [7]. If so, all other accessors to the same value are encoded as empty elements having a local, unqualified attribute named "href" and of type "uri-reference" per the XML Schema Specification [11], with a "href" attribute value of a URI fragment identifier referencing the single element containing the value.
7. It is permissible to encode several references to a value as though these were references to several distinct values, but only when from context it is known that the meaning of the XML instance is unaltered.
8. Arrays are compound values (see also section 5.4.2). SOAP arrays are defined as having a type of "SOAP-ENC:Array" or a type derived there from.

SOAP arrays have one or more dimensions (rank) whose members are distinguished by ordinal position. An array value is represented as a series of elements reflecting the array, with members appearing in ascending ordinal sequence. For multi-dimensional arrays the dimension on the right side varies most rapidly. Each member element is named as an independent element (see rule 2).

SOAP arrays can be single-reference or multi-reference values, and consequently may be represented as the content of either an embedded or independent element.

SOAP arrays MUST contain a "SOAP-ENC:arrayType" attribute whose value specifies the type of the contained elements as well as the dimension(s) of the array. The value of the "SOAP-ENC:arrayType" attribute is defined as follows:

 arrayTypeValue = atype asize atype = QName *( rank ) rank = "[" *( "," ) "]" asize = "[" #length "]" length = 1*DIGIT 

The "atype" construct is the type name of the contained elements expressed as a QName as would appear in the "type" attribute of an XML Schema element declaration and acts as a type constraint (meaning that all values of contained elements are asserted to conform to the indicated type; that is, the type cited in SOAP-ENC:arrayType must be the type or a supertype of every array member). In the case of arrays of arrays or "jagged arrays", the type component is encoded as the "innermost" type name followed by a rank construct for each level of nested arrays starting from 1. Multi-dimensional arrays are encoded using a comma for each dimension starting from 1.

The "asize" construct contains a comma separated list of zero, one, or more integers indicating the lengths of each dimension of the array. A value of zero integers indicates that no particular quantity is asserted but that the size may be determined by inspection of the actual members.

For example, an array with 5 members of type array of integers would have an arrayTypeValue value of "int[][5]" of which the atype value is "int[]" and the asize value is "[5]". Likewise, an array with 3 members of type two-dimensional arrays of integers would have an arrayTypeValue value of "int[,][3]" of which the atype value is "int[,]" and the asize value is "[3]".

A SOAP array member MAY contain a "SOAP-ENC:offset" attribute indicating the offset position of that item in the enclosing array. This can be used to indicate the offset position of a partially represented array (see section 5.4.2.1). Likewise, an array member MAY contain a "SOAP-ENC:position" attribute indicating the position of that item in the enclosing array. This can be used to describe members of sparse arrays (see section 5.4.2.2). The value of the "SOAP-ENC:offset" and the "SOAP-ENC:position" attribute is defined as follows:

 arrayPoint = "[" #length "]" 

with offsets and positions based at 0.

9. A NULL value or a default value MAY be represented by omission of the accessor element. A NULL value MAY also be indicated by an accessor element containing the attribute xsi:null with value '1' or possibly other application-dependent attributes and values.

Note that rule 2 allows independent elements and also elements representing the members of arrays to have names which are not identical to the type of the contained value.

5.2 Simple Types

For simple types, SOAP adopts all the types found in the section "Built-in datatypes" of the "XML Schema Part 2: Datatypes" Specification [11], both the value and lexical spaces. Examples include:

Type	Example
int	58502
float	314159265358979E+1
negativeInteger	-32768
string	Louis "Satchmo" Armstrong

The datatypes declared in the XML Schema specification may be used directly in element schemas. Types derived from these may also be used. An example of a schema fragment and corresponding instance data with elements of these types is:

 <element name="age" type="int"/> <element name="height" type="float"/> <element name="displacement" type="negativeInteger"/> <element name="color"> <simpleType base="xsd:string"> <enumeration value="Green"/> <enumeration value="Blue"/> </simpleType> </element> <age>45</age> <height>5.9</height> <displacement>-450</displacement> <color>Blue</color> 

All simple values MUST be encoded as the content of elements whose type is either defined in "XML Schema Part 2: Datatypes" Specification [11], or is based on a type found there by using the mechanisms provided in the XML Schema specification.

If a simple value is encoded as an independent element or member of a heterogenous array it is convenient to have an element declaration corresponding to the datatype. Because the "XML Schema Part 2: Datatypes" Specification [11] includes type definitions but does not include corresponding element declarations, the SOAP-ENC schema and namespace declares an element for every simple datatype. These MAY be used.

 <SOAP-ENC:int id="int1">45</SOAP-ENC:int> 

5.2.1 Strings

The datatype "string" is defined in "XML Schema Part 2: Datatypes" Specification [11]. Note that this is not identical to the type called "string" in many database or programming languages, and in particular may forbid some characters those languages would permit. (Those values must be represented by using some datatype other than xsd:string.)

A string MAY be encoded as a single-reference or a multi-reference value.

The containing element of the string value MAY have an "id" attribute. Additional accessor elements MAY then have matching "href" attributes.

For example, two accessors to the same string could appear, as follows:

 <greeting id="String-0">Hello</greeting> <salutation href="#String-0"/> 

However, if the fact that both accessors reference the same instance of the string (or subtype of string) is immaterial, they may be encoded as two single-reference values as follows:

 <greeting>Hello</greeting> <salutation>Hello</salutation> 

Schema fragments for these examples could appear similar to the following:

 <element name="greeting" type="SOAP-ENC:string"/> <element name="salutation" type="SOAP-ENC:string"/> 

(In this example, the type SOAP-ENC:string is used as the element's type as a convenient way to declare an element whose datatype is "xsd:string" and which also allows an "id" and "href" attribute. See the SOAP Encoding schema for the exact definition. Schemas MAY use these declarations from the SOAP Encoding schema but are not required to.)

5.2.2 Enumerations

The "XML Schema Part 2: Datatypes" Specification [11] defines a mechanism called "enumeration." The SOAP data model adopts this mechanism directly. However, because programming and other languages often define enumeration somewhat differently, we spell-out the concept in more detail here and describe how a value that is a member of an enumerated list of possible values is to be encoded. Specifically, it is encoded as the name of the value.

"Enumeration" as a concept indicates a set of distinct names. A specific enumeration is a specific list of distinct values appropriate to the base type. For example the set of color names ("Green", "Blue", "Brown") could be defined as an enumeration based on the string built-in type. The values ("1", "3", "5") are a possible enumeration based on integer, and so on. "XML Schema Part 2: Datatypes" [11] supports enumerations for all of the simple types except for boolean. The language of "XML Schema Part 1: Structures" Specification [10] can be used to define enumeration types. If a schema is generated from another notation in which no specific base type is applicable, use "string". In the following schema example "EyeColor" is defined as a string with the possible values of "Green", "Blue", or "Brown" enumerated, and instance data is shown accordingly.

 <element name="EyeColor" type="tns:EyeColor"/> <simpleType name="EyeColor" base="xsd:string"> <enumeration value="Green"/> <enumeration value="Blue"/> <enumeration value="Brown"/> </simpleType> <Person> <Name>Henry Ford</Name> <Age>32</Age> <EyeColor>Brown</EyeColor> </Person> 

5.2.3 Array of Bytes

An array of bytes MAY be encoded as a single-reference or a multi-reference value. The rules for an array of bytes are similar to those for a string.

In particular, the containing element of the array of bytes value MAY have an "id" attribute. Additional accessor elements MAY then have matching "href" attributes.

The recommended representation of an opaque array of bytes is the 'base64' encoding defined in XML Schemas [10][11], which uses the base64 encoding algorithm defined in 2045 [13]. However, the line length restrictions that normally apply to base64 data in MIME do not apply in SOAP. A "SOAP-ENC:base64" subtype is supplied for use with SOAP.

 <picture xsi:type="SOAP-ENC:base64"> aG93IG5vDyBicm73biBjb3cNCg== </picture> 

5.3 Polymorphic Accessor

Many languages allow accessors that can polymorphically access values of several types, each type being available at run time. A polymorphic accessor instance MUST contain an "xsi:type" attribute that describes the type of the actual value.

For example, a polymorphic accessor named "cost" with a value of type "xsd:float" would be encoded as follows:

 <cost xsi:type="xsd:float">29.95</cost> 

as contrasted with a cost accessor whose value's type is invariant, as follows:

 <cost>29.95</cost> 

5.4 Compound types

SOAP defines types corresponding to the following structural patterns often found in programming languages:

• Struct A "struct" is a compound value in which accessor name is the only distinction among member values, and no accessor has the same name as any other.
• Array An "array" is a compound value in which ordinal position serves as the only distinction among member values.

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.

5.4.1 Compound Values, Structs 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":

 <e:Book> <author>Henry Ford</author> <preface>Prefatory text</preface> <intro>This is a book.</intro> </e:Book> 

And this is a schema fragment describing the above structure:

 <element name="Book"> <complexType> <element name="author" type="xsd:string"/> <element name="preface" type="xsd:string"/> <element name="intro" type="xsd:string"/> </complexType> </e:Book> 

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".

 <e:Book> <title>My Life and Work</title> <author href="#Person-1"/> </e:Book> <e:Person id="Person-1"> <name>Henry Ford</name> <address href="#Address-2"/> </e:Person> <e:Address id="Address-2"> <email>mailto:[e-mail]</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:

 <e:Book> <title>My Life and Work</title> <author> <name>Henry Ford</name> <address> <email>mailto:[e-mail]</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:

 <e:Book> <title>My Life and Work</title> <firstauthor href="#Person-1"/> <secondauthor href="#Person-2"/> </e:Book> <e:Person id="Person-1"> <name>Henry Ford</name> <address xsi:type="m:Electronic-address"> <email>mailto:[e-mail]</email> <web>http://www.henryford.com</web> </address> </e:Person> <e:Person id="Person-2"> <name>Samuel Crowther</name> <address xsi:type="n:Street-address"> <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:

 <e:Book> <title>Paradise Lost</title> <firstauthor href="http://www.dartmouth.edu/~milton/"/> </e:Book> 

And this is a schema fragment describing the above structures:

 <element name="Book" type="tns:Book"/> <complexType name="Book"> <!-- Either the following group must occur or else the href attribute must appear, but not both. --> <sequence minOccurs="0" maxOccurs="1"> <element name="title" type="xsd:string"/> <element name="firstauthor" type="tns:Person"/> <element name="secondauthor" type="tns:Person"/> </sequence> <attribute name="href" type="uriReference"/> <attribute name="id" type="ID"/> <anyAttribute namespace="##other"/> </complexType> <element name="Person" base="tns:Person"/> <complexType name="Person"> <!-- Either the following group must occur or else the href attribute must appear, but not both. --> <sequence minOccurs="0" maxOccurs="1"> <element name="name" type="xsd:string"/> <element name="address" type="tns:Address"/> </sequence> <attribute name="href" type="uriReference"/> <attribute name="id" type="ID"/> <anyAttribute namespace="##other"/> </complexType> <element name="Address" base="tns:Address"/> <complexType name="Address"> <!-- Either the following group must occur or else the href attribute must appear, but not both. --> <sequence minOccurs="0" maxOccurs="1"> <element name="street" type="xsd:string"/> <element name="city" type="xsd:string"/> <element name="state" type="xsd:string"/> </sequence> <attribute name="href" type="uriReference"/> <attribute name="id" type="ID"/> <anyAttribute namespace="##other"/> </complexType> 

5.4.2 Arrays

SOAP arrays are defined as having a type of "SOAP-ENC:Array" or a type derived there from (see also rule 8). 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).

Arrays can contain elements which themselves can be of any type, including nested arrays. New types formed by restrictions of SOAP-ENC:Array can also be created to represent, for example, arrays limited to integers or arrays of some user-defined enumeration.

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.

 <element name="myFavoriteNumbers" type="SOAP-ENC:Array"/> <myFavoriteNumbers SOAP-ENC:arrayType="xsd:int[2]"> <number>3</number> <number>4</number> </myFavoriteNumbers> 

In that example, the array "myFavoriteNumbers" contains several members each of which is a value of type SOAP-ENC:int. This can be determined by inspection of the SOAP-ENC:arrayType attribute. Note that the SOAP-ENC:Array type allows unqualified element names without restriction. These convey no type information, so when used they must either have an xsi:type attribute or the containing element must have a SOAP-ENC:arrayType attribute. Naturally, types derived from SOAP-ENC:Array may declare local elements, with type information.

As previously noted, the SOAP-ENC schema contains declarations of elements with names corresponding to each simple type in the "XML Schema Part 2: Datatypes" Specification [11]. It also contains a declaration for "Array". Using these, we might write

 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:int[2]"> <SOAP-ENC:int>3</SOAP-ENC:int> <SOAP-ENC:int>4</SOAP-ENC:int> </SOAP-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 SOAP-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.

 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:ur-type[4]"> <thing xsi:type="xsd:int">12345</thing> <thing xsi:type="xsd:decimal">6.789</thing> <thing xsi:type="xsd: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="xsd:uriReference"> http://www.dartmouth.edu/~milton/reading_room/ </thing> </SOAP-ENC:Array> <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:ur-type[4]"> <SOAP-ENC:int>12345</SOAP-ENC:int> <SOAP-ENC:decimal>6.789</SOAP-ENC:decimal> <xsd:string> Of Mans First Disobedience, and the Fruit Of that Forbidden Tree, whose mortal tast Brought Death into the World, and all our woe, </xsd:string> <SOAP-ENC:uriReference> http://www.dartmouth.edu/~milton/reading_room/ </SOAP-ENC:uriReference > </SOAP-ENC:Array> 

Array values may be structs or other compound values. For example an array of "xyz:Order" structs :

 <SOAP-ENC:Array SOAP-ENC:arrayType="xyz:Order[2]"> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </SOAP-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.

 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[][2]"> <item href="#array-1"/> <item href="#array-2"/> </SOAP-ENC:Array> <SOAP-ENC:Array id="array-1" SOAP-ENC:arrayType="xsd:string[2]"> <item>r1c1</item> <item>r1c2</item> <item>r1c3</item> </SOAP-ENC:Array> <SOAP-ENC:Array id="array-2" SOAP-ENC:arrayType="xsd:string[2]"> <item>r2c1</item> <item>r2c2</item> </SOAP-ENC:Array> 

The element containing an array value does not need to be named "SOAP-ENC:Array". It may have any name, provided that the type of the element is either SOAP-ENC:Array or is derived from SOAP-ENC:Array by restriction. For example, the following is a fragment of a schema and a conforming instance array.

 <simpleType name="phoneNumber" base="string"/> <element name="ArrayOfPhoneNumbers"> <complexType base="SOAP-ENC:Array"> <element name="phoneNumber" type="tns:phoneNumber" maxOccurs="unbounded"/> </complexType> <anyAttribute/> </element> <xyz:ArrayOfPhoneNumbers SOAP-ENC:arrayType="xyz:phoneNumber[2]"> <phoneNumber>206-555-1212</phoneNumber> <phoneNumber>1-888-123-4567</phoneNumber> </xyz:ArrayOfPhoneNumbers> 

Arrays may be multi-dimensional. In this case, more than one size will appear within the asize part of the arrayType attribute:

 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[2,3]"> <item>r1c1</item> <item>r1c2</item> <item>r1c3</item> <item>r2c1</item> <item>r2c2</item> <item>r2c3</item> </SOAP-ENC:Array> 

While the examples above have shown arrays encoded as independent elements, array values MAY also appear embedded and SHOULD do so when they are known to be single reference.

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 "phone-numbers":

 <simpleType name="phoneNumber" base="string"/> <element name="ArrayOfPhoneNumbers"> <complexType base="SOAP-ENC:Array"> <element name="phoneNumber" type="tns:phoneNumber" maxOccurs="unbounded"/> </complexType> <anyAttribute/> </element> <element name="Person"> <complexType> <element name="name" type="string"/> <element name="phoneNumbers" type="tns:ArrayOfPhoneNumbers"/> </complexType> </element> <xyz:Person> <name>John Hancock</name> <phoneNumbers SOAP-ENC:arrayType="xyz:phoneNumber[2]"> <phoneNumber>206-555-1212</phoneNumber> <phoneNumber>1-888-123-4567</phoneNumber> </phoneNumbers> </xyz:Person> 

Here is another example of a single-reference array value encoded as an embedded element whose containing element name is the accessor name:

 <xyz:PurchaseOrder> <CustomerName>Henry Ford</CustomerName> <ShipTo> <Street>5th Ave</Street> <City>New York</City> <State>NY</State> <Zip>10010</Zip> </ShipTo> <PurchaseLineItems SOAP-ENC:arrayType="Order[2]"> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </PurchaseLineItems> </xyz:PurchaseOrder> 

5.4.2.1 Partially Transmitted Arrays

SOAP provides support for partially transmitted arrays, known as "varying" arrays in some contexts [12]. A partially transmitted array indicates in an "SOAP-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:

 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[5]" SOAP-ENC:offset="[2]"> <item>The third element</item> <item>The fourth element</item> </SOAP-ENC:Array> 

5.4.2.2 Sparse Arrays

SOAP provides support for sparse arrays. Each element representing a member value contains a "SOAP-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:

 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[,][4]"> <SOAP-ENC:Array href="#array-1" SOAP-ENC:position="[2]"/> </SOAP-ENC:Array> <SOAP-ENC:Array id="array-1" SOAP-ENC:arrayType="xsd:string[10,10]"> <item SOAP-ENC:position="[2,2]">Third row, third col</item> <item SOAP-ENC:position="[7,2]">Eighth row, third col</item> </SOAP-ENC:Array> 

If the only reference to array-1 occurs in the enclosing array, this example could also have been encoded as follows:

 <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[,][4]"> <SOAP-ENC:Array SOAP-ENC:position="[2]" SOAP-ENC:arrayType="xsd:string[10,10]> <item SOAP-ENC:position="[2,2]">Third row, third col</item> <item SOAP-ENC:position="[7,2]">Eighth row, third col</item> </SOAP-ENC:Array> </SOAP-ENC:Array> 

5.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.

 <xyz:PurchaseOrder> <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) SOAP-ENC:Array. For example:

 <PurchaseLineItems> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </PurchaseLineItems> 

5.5 Default Values

An omitted accessor element implies either a default value or that no value is known. The specifics depend on the accessor, method, and its context. For example, an omitted accessor typically implies a Null value for polymorphic accessors (with the exact meaning of Null accessor-dependent). Likewise, an omitted Boolean accessor typically implies either a False value or that no value is known, and an omitted numeric accessor typically implies either that the value is zero or that no value is known.

5.6 SOAP root Attribute

The SOAP root attribute can be used to label serialization roots that are not true roots of an object graph so that the object graph can be deserialized. The attribute can have one of two values, either "1" or "0". True roots of an object graph have the implied attribute value of "1". Serialization roots that are not true roots can be labeled as serialization roots with an attribute value of "1" An element can explicitly be labeled as not being a serialization root with a value of "0".

The SOAP root attribute MAY appear on any subelement within the SOAP Header and SOAP Body elements. The attribute does not have a default value.