Copyright © 2001 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
SOAP version 1.2 is a lightweight protocol for exchange of information in a decentralized, distributed environment. It is an XML based protocol that consists of four parts: an envelope that defines a framework for describing what is in a message and how to process it, a transport binding framework for exchanging messages using an underlying protocol, a set of encoding rules for expressing instances of application-defined data types and a convention for representing remote procedure calls and responses. Part 2 (this document) describes the RPC convention and encoding rules along with a concrete HTTP binding specification; the SOAP envelope and transport binding framework are described in Part 1[1].
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This is the second W3C Working Draft of the SOAP Version 1.2 specification for review by W3C members and other interested parties. It has been produced by the XML Protocol Working Group (WG), which is part of the XML Protocol Activity.
The specification has been split into two documents: SOAP Version 1.2 Part 1: Messaging Framework which describes the SOAP envelope and the SOAP transport binding framework, and SOAP Version 1.2 Part 2: Adjuncts, which describes the SOAP encoding rules the SOAP RPC convention and a concrete HTTP binding specification.
For a detailed list of changes since the last publication of this document, refer to appendix C Part 2 Change Log. A list of open issues against this document can be found at http://www.w3.org/2000/xp/Group/xmlp-issues.
Comments on this document should be sent to xmlp-comments@w3.org (public archive[12]). It is inappropriate to send discussion emails to this address.
Discussion of this document takes place on the public xml-dist-app@w3.org mailing list[13] per the email communication rules in the XML Protocol Working Group Charter[14].
This is a public W3C Working Draft. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of all W3C technical reports can be found at http://www.w3.org/TR/.
1 Introduction
1.1 Notational Conventions
1.2 Examples of SOAP Messages
1.3 SOAP Terminology
1.3.1 Data Encoding Concepts
2 Relation to XML
3 The SOAP Data Model
4 SOAP Encoding
4.1 Rules for Encoding Types in XML
4.2 Simple Types
4.2.1 Strings
4.2.2 Enumerations
4.2.3 Array of Bytes
4.3 Polymorphic Accessor
4.4 Compound Types
4.4.1 Compound Values and References to Values
4.4.2 Arrays
4.4.2.1 PartiallyTransmitted Arrays
4.4.2.2 SparseArrays
4.4.3 Generic Compound Types
4.5 Default Values
4.6 SOAP root Attribute
5 Using SOAP for RPC
5.1 RPC and SOAP Body
5.2 RPC and SOAP Header
5.3 RPC Faults
6 Using SOAP in HTTP
6.1 SOAP HTTP Request
6.1.1 The SOAPAction HTTP Header Field
6.2 SOAP HTTP Response
6.3 The HTTP Extension Framework
6.4 Security Considerations
6.5 SOAP HTTP Examples
7 References
7.1 Normative References
7.2 Informative References
A SOAP Envelope Examples (Non-Normative)
A.1 Sample Encoding of Call Requests
A.2 Sample Encoding of Response
B Acknowledgements (Non-Normative)
C Part 2 Change Log (Non-Normative)
C.1 SOAP Specification Changes
C.2 XML Schema Changes
SOAP version 1.2 provides a simple and lightweight mechanism for exchanging structured and typed information between peers in a decentralized, distributed environment using XML. SOAP does not itself define any application semantics such as a programming model or implementation specific semantics; rather it defines a simple mechanism for expressing application semantics by providing a modular packaging model and encoding mechanisms for encoding application defined data. This allows SOAP to be used in a large variety of systems ranging from messaging systems to remote procedure calls (RPC).
SOAP consists of four parts:
The SOAP envelope [1](SOAP Envelope) construct defines an overall framework for expressing what is in a message, who should deal with it, and whether it is optional or mandatory.
The SOAP binding framework [1](SOAP Transport Binding Framework) defines an abstract framework for exchanging SOAP envelopes between peers using an underlying protocol for transport. The SOAP HTTP binding 6 Using SOAP in HTTP) defines a concrete instance of a binding to the HTTP protocol[2].
The SOAP encoding rules (4 SOAP Encoding) define a serialization mechanism that can be used to exchange instances of application-defined datatypes.
The SOAP RPC representation (5 Using SOAP for RPC) defines a convention that can be used to represent remote procedure calls and responses.
These four parts are functionally orthogonal. In recognition of this, the envelope and the encoding rules are defined in different namespaces.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [3].
The namespace prefixes "env" and "enc" used in the prose sections of this document are associated with the SOAP namespace names "http://www.w3.org/2001/09/soap-envelope" and "http://www.w3.org/2001/09/soap-encoding" respectively.
The namespace prefixes "xs" and "xsi" used in the prose sections of this document are associated with the namespace names "http://www.w3.org/2001/XMLSchema" and "http://www.w3.org/2001/XMLSchema-instance" respectively, both of which are defined in the XML Schemas specification[4],[5].
Note that the choice of any namespace prefix is arbitrary and not semantically significant.
Namespace URIs of the general form "http://example.org/..." and "http://example.com/..." represent an application-dependent or context-dependent URI[6].
This specification uses the augmented Backus-Naur Form (BNF) as described in [2].
SOAP messages may be bound to different underlying protocols and used in a variety of message exchange patterns. The following two examples show SOAP used in connection with HTTP as the underlying protocol taking advantage of the request/response mechanism provided by HTTP (6 Using SOAP in HTTP).
The following example shows a sample SOAP/HTTP request. The
SOAP/HTTP request contains a block called
GetLastTradePrice
which takes a single parameter,
the ticker symbol for a stock. Note that the
GetLastTradePrice
element is not defined by SOAP
itself. The service's response to this request contains a
single parameter, the price of the stock. The SOAP
Envelope
element is the top element of the XML
document representing the SOAP message. XML namespaces are
used to disambiguate SOAP identifiers from application
specific identifiers.
POST /StockQuote HTTP/1.1 Host: www.example.org Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://example.org/2001/06/quotes" <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > <env:Body> <m:GetLastTradePrice env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" xmlns:m="http://example.org/2001/06/quotes"> <symbol>DIS</symbol> </m:GetLastTradePrice> </env:Body> </env:Envelope>
The following example shows the SOAP message sent by the StockQuote service in response to the request shown in the preceeding example.
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > <env:Body> <m:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" xmlns:m="http://example.org/2001/06/quotes"> <Price>34.5</Price> </m:GetLastTradePriceResponse> </env:Body> </env:Envelope>
More examples are available in A SOAP Envelope Examples.
All SOAP messages have an XML Information Set[10]
A SOAP node MUST ensure that all element information items and attribute information items in messages that it generates are correctly namespace qualified. A SOAP node MUST be able to process SOAP namespace information in messages that it receives. It MUST discard messages that have incorrect namespace information (see [1]SOAP Fault)
This document defines the following namespaces[7]:
The SOAP serialisation has the namespace identifier "http://www.w3.org/2001/09/soap-encoding"
The RPC result element has the namespace identifier "http://www.w3.org/2001/09/soap-rpc"
A schema document for these namespace can be found by dereferencing the relevant namespace identifier.
A SOAP message MUST NOT contain a Document Type Declaration. A SOAP message MUST NOT contain processing instruction information items[8].
SOAP uses unqualified attribute information
items with a local name of id
and a type
of ID in the
http://www.w3.org/2001/XMLSchema namespace to
specify the unique identifier of an encoded element. SOAP uses
unqualified attribute information items with a
local name of href
and a type of
anyURI in the
http://www.w3.org/2001/XMLSchema namespace to
specify a reference to such a value, in a manner conforming to
the XML Specification[8], XML Schema
Specification[5], and XML Linking
Language Specification[9].
A SOAP message MUST NOT impose any XML schema processing (assessment and validation) requirement on the part of any receiving SOAP node. Therefore, SOAP REQUIRES that all attribute information items, whether specified in this specification or whether they belong to a foreign namespace be carried in the serialized SOAP envelope.
Editorial note: JJM | 20010914 |
Section 4 currently defines a data model in the form of a directed graph. Elements of the data model include struct, array, and id/href. In addition to the data model, section 4 includes a particular encoding of that model without clearly separating the two. The WG would like to clarify the relationship between the data model and the particular encoding by saying that the SOAP encoding is one of several potential encodings of the SOAP data model. This section is the placeholder for the description of the SOAP data model (see also section 3.5 in the XML Protocol WG Draft Requirements) |
Editorial note: JJM | 20010920 |
The Working Group is aware that the following section does not use the XML Infoset terminology used elsewhere in this specification, and most notably in Part 1. The WG expects to rewrite this section using the XML Infoset terminalogy at a later date. |
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 data serialized according to the rules defined in this section MAY contain references to data outside the serialization. When present, these references MUST be Uniform Resource Identifiers (see [6]).
The namespace identifier for the elements and attributes defined in this section is "http://www.w3.org/2001/09/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 [1]SOAP Encoding Attribute).
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 5 Using SOAP for RPC.
To describe encoding, the following terminology is used:
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.
A "simple value" is one without named parts. Examples of simple values are particular strings, integers, enumerated values etc.
A "compound value" is an aggregate of relations to other values. Examples of Compound Values are particular purchase orders, stock reports, street addresses, etc.
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.
An "array" is a compound value in which ordinal position serves as the only distinction among member values.
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.
A "simple type" is a class of simple values. Examples of simple types are the classes called "string," "integer," enumeration classes, etc.
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).
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."
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.
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"
[4] and "XML Schema Part 2: Datatypes"
[5] 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:
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).
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)
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.
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[5] or whose source type is listed therein (see also 4.2 Simple Types).
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 4.4 Compound Types).
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 [8]. 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[5], with a href
attribute value
of a URI fragment identifier referencing the corresponding
independent element.
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 4.2.1 Strings and 4.2.3 Array of Bytes ). An accessor to a string or
byte-array value MAY have an attribute named id
and of type "ID" per the XML Specification[8]. 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[5],
with a href
attribute value of a URI fragment
identifier referencing the single element containing the
value.
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.
Arrays are compound values (see also 4.4.2 Arrays). SOAP arrays are defined as having a type of "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 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 enc:arrayType
attribute is defined as
follows:
enc:arrayType
[1] | arrayTypeValue | = | atype asize |
[2] | atype | = | QName *( rank ) |
[3] | rank | = | "[" *( "," ) "]" |
[4] | asize | = | "[" #length "]" |
[5] | 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 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 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 4.4.2.1 PartiallyTransmitted Arrays). Likewise, an array member MAY contain
a enc:position
attribute indicating the position
of that item in the enclosing array. This can be used to
describe members of sparse arrays (see 4.4.2.2 SparseArrays). The value of the enc:offset
and the
enc:position
attribute is defined as follows:
enc:offset
and
enc:position
[6] | arrayPoint | = | "[" #length "]" |
with offsets and positions based at 0.
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:nil
with value
"1 or true" 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.
For simple types, SOAP adopts all the types found in the section "Built-in datatypes" of the "XML Schema Part 2: Datatypes" Specification[5], 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. For example, for the following schema:
<!-- schema document --> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" > <xs:element name="age" type="xs:int" /> <xs:element name="height" type="xs:float" /> <xs:element name="displacement" type="xs:negativeInteger" /> <xs:element name="color" > <xs:simpleType base="xsd:string"> <xs:restriction base="xs:string"> <xs:enumeration value="Green"/> <xs:enumeration value="Blue"/> </xs:restriction> </xs:simpleType> </xs:element> </xs:schema>
the following elements would be valid instances:
<!-- Example instance elements --> <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[5], 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[5] includes type definitions but does not include corresponding element declarations, the enc schema and namespace declares an element for every simple datatype. These MAY be used.
<enc:int xmlns:enc="http://www.w3.org/2001/09/soap-encoding" id="int1">45</enc:int>
The datatype "string" is defined in "XML Schema Part 2: Datatypes" Specification[5]. 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:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/soap-encoding" > <xs:import namespace="http://www.w3.org/2001/09/soap-encoding" /> <xs:element name="greeting" type="enc:string" /> <xs:element name="salutation" type="enc:string" /> </xs:schema>
(In this example, the type 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 id
and href
attributes. See the SOAP Encoding schema for the
exact definition. Schemas MAY use these declarations from
the SOAP Encoding schema but are not required to.)
The "XML Schema Part 2: Datatypes" Specification[5] defines a mechanism called "enumeration." The SOAP data model adopts this mechanism directly. However, because programming and other languages often define enumeration somewhat differently, the specification further describes 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"[5] supports enumerations for all of the simple types except for boolean. The language of "XML Schema Part 1: Structures" Specification[4] 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.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://example.org/2001/06/samples" targetNamespace="http://example.org/2001/06/samples" > <xs:element name="EyeColor" type="tns:EyeColor" /> <xs:simpleType name="EyeColor" > <xs:restriction base="xs:string" > <xs:enumeration value="Green" /> <xs:enumeration value="Blue" /> <xs:enumeration value="Brown" /> </xs:restriction> </xs:simpleType> </xs:schema>
<p:EyeColor xmlns:p="http://example.org/2001/06/samples" >Brown</p:EyeColor>
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[4][5], which uses the base64 encoding algorithm defined in MIME[15]. However, the line length restrictions that normally apply to base64 data in MIME do not apply in SOAP. A "enc:base64" subtype is supplied for use with SOAP.
<picture xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:enc="http://www.w3.org/2001/09/soap-encoding" xsi:type="enc:base64" > aG93IG5vDyBicm73biBjb3cNCg== </picture>
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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:float">29.95</cost>
as contrasted with a cost accessor whose value's type is invariant, as follows:
<cost>29.95</cost>
SOAP defines types corresponding to the following structural patterns often found in programming languages:
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.
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.
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 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:
<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.
<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:
<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:
<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:
<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:
<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>
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:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/soap-encoding" > <xs:import namespace="http://www.w3.org/2001/09/soap-encoding" /> <xs:element name="myFavoriteNumbers" type="enc:Array" /> </xs:schema>
<myFavoriteNumbers xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/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:
enc:Array
element<enc:Array xmlns:enc="http://www.w3.org/2001/09/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:
<enc:Array xmlns:enc="http://www.w3.org/2001/09/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>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/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 :
<enc:Array xmlns:enc="http://www.w3.org/2001/09/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.
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/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/09/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/09/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:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/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>
<abc:ArrayOfPhoneNumbers xmlns:abc="http://example.org/2001/06/numbers" xmlns:enc="http://www.w3.org/2001/09/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:
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/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 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 "phoneNumbers":
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/09/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/09/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>
<def:Person xmlns:def="http://example.org/2001/06/numbers" xmlns:enc="http://www.w3.org/2001/09/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:
<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/09/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>
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:
<enc:Array xmlns:enc="http://www.w3.org/2001/09/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>
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:
<enc:Array xmlns:enc="http://www.w3.org/2001/09/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:
<enc:Array xmlns:enc="http://www.w3.org/2001/09/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>
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 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:
<PurchaseLineItems> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </PurchaseLineItems>
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.
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 "true" or
"false". True roots of an object graph have
the implied attribute value of "true".
Serialization roots that are not true roots can be labeled as
serialization roots with an attribute value of
"true". An element can explicitly be labeled as
not being a serialization root with a value of
"false".
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.
The SOAP root
attribute information item
is of type boolean from the namespace
"http://www.w3.org/2001/XMLSchema".
Editorial note: JJM | 20010920 |
The Working Group is aware that the following section does not use the XML Infoset terminology used elsewhere in this specification, and most notably in Part 1. The WG expects to rewrite this section using the XML Infoset terminalogy at a later date. |
One of the design goals of SOAP is to encapsulate remote procedure call functionality using the extensibility and flexibility of XML. This section defines a uniform representation of RPC invocations and responses.
Although it is anticipated that this representation is likely to be used in combination with the encoding style defined in 4 SOAP Encoding, other representations are possible. The SOAP encodingStyle attribute (see [1]SOAP Encoding Attribute) can be used to indicate the encoding style of the RPC invocation and/or the response using the representation described in this section.
Using SOAP for RPC is orthogonal to the SOAP protocol binding (see 6 Using SOAP in HTTP). In the case of using HTTP as the protocol binding, an RPC invocation maps naturally to an HTTP request and an RPC response maps to an HTTP response. However, using SOAP for RPC is not limited to the HTTP protocol binding.
To invoke an RPC, the following information is needed:
The URI of the target SOAP node
A procedure or method name
An optional procedure or method signature
The parameters to the procedure or method
Optional header data
SOAP relies on the protocol binding to provide a mechanism for carrying the URI. For example, for HTTP the request URI indicates the resource that the invocation is being made against. Other than it be a valid URI, SOAP places no restriction on the form of an address (see RFC2396[6] for more information on URIs).
RPC invocations and responses are both carried in the SOAP
Body
element (see [1]SOAP Body)
using the following representation:
An RPC invocation is modeled as a struct.
The invocation is viewed as a single struct containing an accessor for each [in] or [in/out] parameter. The struct is both named and typed identically to the procedure or method name.
Each [in] or [in/out] parameter is viewed as an accessor, with a name corresponding to the name of the parameter and type corresponding to the type of the parameter. These appear in the same order as in the procedure or method signature.
An RPC response is modeled as a struct.
The response is viewed as a single struct containing an accessor for the return value and each [out] or [in/out] parameter. The return value accessor SHOULD be first, followed by the accessors for the parameters which SHOULD be in the same order as they appear in the procedure or method signature.
Each parameter accessor has a name corresponding to the name of the parameter and type corresponding to the type of the parameter. The name of the return value accessor is "result" and it is namespace-qualified with the namespace identifier "http://www.w3.org/2001/09/soap-rpc" The return value accessor MUST be present if the return value of the procedure is non-void. The return value accessor MUST NOT be present if the return value of the procedure is void.
Invocation faults are handled according to the rules in 5.3 RPC Faults. If a protocol binding adds additional rules for fault expression, those MUST also be followed.
As noted above, RPC invocation and response structs can be
encoded according to the rules in 4 SOAP Encoding, or
other encodings can be specified using the encodingStyle
attribute (see [1]Encoding Attribute).
Applications MAY process invocations with missing parameters but also MAY return a fault.
Because a result indicates success and a fault indicates failure, it is an error for an RPC response to contain both a result and a fault.
Additional information relevant to the encoding of an RPC invocation but not part of the formal procedure or method signature MAY be expressed in the RPC encoding. If so, it MUST be expressed as a header block.
An example of the use of a header block is the passing of a transaction ID along with a message. Since the transaction ID is not part of the signature and is typically held in an infrastructure component rather than application code, there is no direct way to pass the necessary information with the invocation. By adding a header block with a fixed name, the transaction manager on the receiving side can extract the transaction ID and use it without affecting the coding of remote procedure calls.
The RPC representation introduces additional SOAP fault
codes to those described in [1]Fault Codes. The
namespace identifier for these SOAP faultcode
element information item values is
"http://www.w3.org/2001/09/soap-rpc" and the
namespace prefix rpc:
is used in this section to
indicate association with this namespace.
Errors arising during RPC invocations are reported according to the following rules (in decreasing order of precedence):
A soap-env:Server
fault SHOULD be
generated when the server cannot handle the message because
of some temporary condition, e.g. when it is out of
memory.
A soap-env:DataEncodingUnknown
fault
SHOULD be generated when the arguments are encoded in a
data encoding unknown to the server.
An rpc:ProcedureNotPresent
fault MUST be
generated when the server cannot find the procedure
specified.
An rpc:BadArguments
fault MUST be
generated when the server cannot parse the arguments or
when there is a mismatch between what the server expects
and what the client has sent.
Other faults arising in an extension or from the application SHOULD be generated as described in [1](SOAP Faults).
In all cases the values of the detail
and
faultstring
element information items
are implementation defined. They MAY be specified by some
external document.
This section describes how to use SOAP within HTTP. Binding SOAP to HTTP provides the advantage of being able to use the formalism and decentralized flexibility of SOAP with the rich feature set of HTTP. Carrying SOAP in HTTP does not mean that SOAP overrides existing semantics of HTTP but rather that SOAP over HTTP inherits HTTP semantics.
SOAP naturally follows the HTTP request/response message model by providing a SOAP request message in a HTTP request and SOAP response message in a HTTP response. Note, however, that SOAP intermediaries are NOT the same as HTTP intermediaries. That is, an HTTP intermediary addressed with the HTTP Connection header field cannot be expected to inspect or process the SOAP entity body carried in the HTTP request.
HTTP applications MUST use the media type "text/xml" according to RFC 2376[11] when including SOAP messages in HTTP exchanges.
Although SOAP might be used in combination with a variety of HTTP request methods, this binding only defines SOAP within HTTP POST requests (see 5 Using SOAP for RPC for how to use SOAP for RPC).
Editorial note: JJM | 20010821 |
SOAPAction is an optional feature of SOAP. The Working Group is considering a formal definition of the general characteristics of such "optional features" for inclusion in a future revision of this specification. At such time, the above description of SOAPAction would be revised, if necessary, to make clear its status as such a feature. |
Some SOAP Receivers using this binding might need certain information to be readily available within the underlying protocol. This binding uses the SOAPAction HTTP request header field to supply this information.
[7] | soapaction | = | "SOAPAction" ":" <"> URI-reference <"> |
[8] | URI-reference | = | <as defined in RFC2396> |
The value of this request header field can be any URI reference, including absolute URIs and relative URIs, in which case it is interpreted relative to the Request-URI.
SOAPAction's presence in this binding's request messages is OPTIONAL. SOAP Receivers MAY use it as a hint to optimise processing, but SHOULD NOT require its presence in order to operate.
Editorial note: JJM | 20010818 |
A specific HTTP Status Code (427 proposed) shall be registered with IANA for the purpose of providing a means by which a SOAP Receiver can indicate to a SOAP client that the SOAPAction Header Field is required. |
If a SOAP Receiver does require SOAPAction's presence in order to operate, it MUST respond to requests which either contain an unrecognised SOAPAction header value or do not contain a SOAPAction header with a 427 "SOAPAction Required" HTTP response status code. Such response messages MAY contain a 'Required-SOAPAction' HTTP response header field, whose value is the URI which can be used in the SOAPAction request header field to re-submit the request.
[9] | req-soapaction | = | "required-SOAPAction" ":" <"> URI-reference <"> |
Support for SOAPAction is OPTIONAL in implementations. Implementations SHOULD NOT generate or require SOAPAction UNLESS they have a particular purpose for doing so (e.g., a SOAP Receivers specifies its use).
SOAP over HTTP follows the semantics of the HTTP Status codes for communicating status information in HTTP. For example, a 2xx status code indicates that the client's request including the SOAP component was successfully received, understood, and accepted etc.
If an error occurs while processing the request, the SOAP HTTP server MUST issue an HTTP 500 "Internal Server Error" response and include a SOAP message in the response containing a SOAP fault (see [1]SOAP Faults) indicating the SOAP processing error.
Editorial note: MJH | 20010809 |
Due to it's status as an experimental RFC[17], all normative references to the HTTP extension framework[16] have been removed from this specification. Unless feedback to the contrary is received, the remains of this subsection, including this note, will be removed from the next working draft. |
Editorial note: MJG | 20010926 |
This section will in a future revision provide some guidelines for the security considerations that should be taken into account when using the HTTP binding defined in this document. |
POST /StockQuote HTTP/1.1 Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://www.example.org/abc#MyMessage" <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > . . . </env:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > . . . </env:Envelope>
POST /StockQuote HTTP/1.1 Host: www.example.org Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://example.org/2001/06/quotes" <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > <env:Header> <t:Transaction xmlns:t="http://example.org/2001/06/tx" env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" env:mustUnderstand="1" > 5 </t:Transaction> </env:Header> <env:Body > <m:GetLastTradePrice env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <m:symbol>DEF</m:symbol> </m:GetLastTradePrice> </env:Body> </env:Envelope>
POST /StockQuote HTTP/1.1 Host: www.example.org Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://example.org/2001/06/quotes" <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > <env:Body> <m:GetLastTradePriceDetailed env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <Symbol>DEF</Symbol> <Company>DEF Corp</Company> <Price>34.1</Price> </m:GetLastTradePriceDetailed> </env:Body> </env:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > <env:Header> <t:Transaction xmlns:t="http://example.org/2001/06/tx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:int" env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" env:mustUnderstand="1" > 5 </t:Transaction> </env:Header> <env:Body> <m:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <Price>34.5</Price> </m:GetLastTradePriceResponse> </env:Body> </env:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > <env:Body> <m:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/09/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <PriceAndVolume> <LastTradePrice>34.5</LastTradePrice> <DayVolume>10000</DayVolume> </PriceAndVolume> </m:GetLastTradePriceResponse> </env:Body> </env:Envelope>
HTTP/1.1 500 Internal Server Error Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> <env:Body> <env:Fault> <faultcode>env:MustUnderstand</faultcode> <faultstring>SOAP Must Understand Error</faultstring> </env:Fault> </env:Body> </env:Envelope>
HTTP/1.1 500 Internal Server Error Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" > <env:Body> <env:Fault> <faultcode>env:Server</faultcode> <faultstring>Server Error</faultstring> <detail> <e:myfaultdetails xmlns:e="http://example.org/2001/06/faults" > <message>My application didn't work</message> <errorcode>1001</errorcode> </e:myfaultdetails> </detail> </env:Fault> </env:Body> </env:Envelope>
This document is the work of the W3C XML Protocol Working Group.
Members of the Working Group are (at the time of writing, and by alphabetical order): Yasser al Safadi (Philips Research), Vidur Apparao (Netscape), Don Box (DevelopMentor), Charles Campbell (Informix Software), Michael Champion (Software AG), Dave Cleary (webMethods), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Ron Daniel (Interwoven), Glen Daniels (Allaire), Doug Davis (IBM), Ray Denenberg (Library of Congress), Paul Denning (MITRE Corporation), Frank DeRose (TIBCO Software, Inc.), James Falek (TIBCO Software, Inc.), David Fallside (IBM), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dietmar Gaertner (Software AG), Rich Greenfield (Library of Congress), Martin Gudgin (DevelopMentor), Hugo Haas (W3C), Marc Hadley (Sun Microsystems), Mark Hale (Interwoven), Randy Hall (Intel), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), Yin-Leng Husband (Compaq), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.), Scott Isaacson (Novell, Inc.), Kazunori Iwasa (Fujitsu Software Corporation), Murali Janakiraman (Rogue Wave), Mario Jeckle (Daimler-Chrysler Research and Technology), Eric Jenkins (Engenia Software), Mark Jones (AT&T), Anish Karmarkar (Oracle), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Jacek Kopecky (IDOOX s.r.o.), Yves Lafon (W3C), Tony Lee (Vitria Technology Inc.), Michah Lerner (AT&T), Henry Lowe (OMG), Richard Martin (Active Data Exchange), Noah Mendelsohn (Lotus Development), Jeff Mischinsky (Oracle), Nilo Mitra (Ericsson Research Canada), Jean-Jacques Moreau (Canon), Highland Mary Mountain (Intel), Masahiko Narita (Fujitsu Software Corporation), Mark Needleman (Data Research Associates), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), Mark Nottingham (Akamai Technologies), David Orchard (BEA Systems), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Andreas Riegg (Daimler-Chrysler Research and Technology), Herve Ruellan (Canon), Marwan Sabbouh (MITRE Corporation), Shane Sesta (Active Data Exchange), Miroslav Simek (IDOOX s.r.o.), Simeon Simeonov (Allaire), Nick Smilonich (Unisys), Soumitro Tagore (Informix Software), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Asir Vedamuthu (webMethods) Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Stuart Williams (Hewlett-Packard), Amr Yassin (Philips Research) and Jin Yu (Martsoft Corp.).
Previous members were: Eric Fedok (Active Data Exchange), Susan Yee (Active Data Exchange), Dan Frantz (BEA Systems), Alex Ceponkus (Bowstreet), James Tauber (Bowstreet), Rekha Nagarajan (Calico Commerce), Mary Holstege (Calico Commerce), Krishna Sankar (Cisco Systems), David Burdett (Commerce One), Murray Maloney (Commerce One), Jay Kasi (Commerce One), Yan Xu (DataChannel), Brian Eisenberg (DataChannel), Mike Dierken (DataChannel), Michael Freeman (Engenia Software), Bjoern Heckel (Epicentric), Dean Moses (Epicentric), Julian Kumar (Epicentric), Miles Chaston (Epicentric), Alan Kropp (Epicentric), Scott Golubock (Epicentric), Michael Freeman (Engenia Software), Jim Hughes (Fujitsu Limited), Dick Brooks (Group 8760), David Ezell (Hewlett Packard), Fransisco Cubera (IBM), David Orchard (Jamcracker), Alex Milowski (Lexica), Steve Hole (MessagingDirect Ltd.), John-Paul Sicotte (MessagingDirect Ltd.), Vilhelm Rosenqvist (NCR), Lew Shannon (NCR), Art Nevarez (Novell, Inc.), David Clay (Oracle), Jim Trezzo (Oracle), David Cleary (Progress Software), Andrew Eisenberg (Progress Software), Peter Lecuyer (Progress Software), Ed Mooney (Sun Microsystems), Mark Baker (Sun Microsystems), Anne Thomas Manes (Sun Microsystems), George Scott (Tradia Inc.), Erin Hoffmann (Tradia Inc.), Conleth O'Connell (Vignette), Waqar Sadiq (Vitria Technology Inc.), Randy Waldrop (WebMethods), Bill Anderson (Xerox), Tom Breuel (Xerox), Matthew MacKenzie (XMLGlobal Technologies), David Webber (XMLGlobal Technologies), John Evdemon (XMLSolutions) and Kevin Mitchell (XMLSolutions).
The people who have contributed to discussions on xml-dist-app@w3.org are also gratefully acknowledged.
Date | Author | Description |
---|---|---|
20010926 | MJG | Updated member list |
20010926 | MJG | Updated ednote in section 6.4 |
20010926 | MJG | Changed rpc namespace to http://www.w3.org/2001/09/soap-rpc |
20010921 | MJG | Added rpc namespace to list in Section 2 |
20010921 | MJG | Added new schema for rpc result element as described in section 5.1 |
20010921 | MJG | Amended section 5.1 to incorporate description of rpc result element |
20010921 | MJG | Changed targetNamespace attribute of encoding schema to http://www.w3.org/2001/09/soap-encoding |
20010921 | JJM | Used text proposed by Noah for ednote on SOAPAction. |
20010920 | JJM | Make the wording clarification regarding issue 45 (descreasing order of precedence). |
20010920 | JJM | Removed current security section; added new security subsection to HTTP binding section, with a temporary ednote until we get text from Henrik and Chris). |
20010920 | JJM | Change the namespace of the envelope to http://www.w3.org/2001/09/... |
20010920 | JJM | Add an editorial note about why some sections are not written in terms of infoset. |
20010920 | JJM | Add ednote from Jacek regarding SOAPAction. |
20010918 | JJM | Added ednote to the "SOAPAction" section indicating that a HTTP status code needs to be obtained from IANA. |
20010918 | JJM | Removed last electrocommerce.org URL from examples. |
20010914 | JJM | Added text from Henrik to beef-up the "Data Model" section placeholder text. |
20010914 | JJM | Back to "Adjuncts" again. |
20010914 | JJM | Fixed issues 124, 126, 127, 128 and 132. |
20010914 | JJM | Fixed typos and indentation. |
20010914 | JJM | Reference the XML InfoSet Proposed Recommandation instead of the Candidate Recommandation. |
20010911 | JJM | Changed XML Information Set into a normative reference. Changed XML Protocol Comments Archive, Discussion Archive and Charter into non-normative references. Added a reference to RFC2396 in section 4, 3rd paragraph. |
20010905 | MJH | Wordsmithed abstract and introduction to better reflect split into parts 1 and 2. Rationalised list of references so only cited works appear. Removed envelope schema changes. Added bibref entries for cross references to Part 1, fixed links so they target the HTML instead of XML version of the doc. |
20010831 | JJM | Added a close paragraph tag before starting a new olist or ulist. |
20010831 | JJM | Properly declared the language for the spec, so that we can generate valid HTML. |
20010831 | JJM | Added text from Hugo to emphasize the fact that the SOAP root attribute is of type XMLSchema boolean. |
20010830 | MJG | Copied "Relation to XML" section from part 1. |
20010830 | MJG | Removed Design Goals section (design goals listed relevant to Part 1 not Part 2) |
20010830 | JJM | Removed terminology not relevant to part2. |
20010830 | JJM | Added SOAP examples from part 1, introductory sections. |
20010830 | JJM | Added SOAP example appendix from part1. |
20010830 | JJM | Added a paragraph to section 1 pointing to part2 for encoding, rpc and http binding. |
20010830 | JJM | Added a paragraph at the beginning of section 3 to cover serializations containing references to data outside the serialization, as per 20010829 teleconference. |
20010830 | JJM | Remove 2nd sentence, bullet 5, RPC faults section, as per 20010829 teleconference. |
20010830 | JJM | Remove 2nd sentence, bullet 1, RPC faults section, as per 20010822 teleconference. |
20010829 | JJM | Added a placehoder for the forthcoming Data Model section. |
20010829 | JJM | Removed the Envelope Example section, already present in part1. |
20010829 | JJM | Updated the spec's title. |
20010829 | JJM | Replaced specref with xspecref for references to Part1 items. |
20010829 | JJM | Added bibliography entry for SOAP 1.2 Part 1. |
20010829 | JJM | Removed former sections 1, 2, 3 and 4, and the SOAP versioning appendix. Moved the RPC section before the HTTP binding section, as per the 20010815 teleconference call. |
20010829 | JJM | Did split the spec into two parts. |
20010829 | JJM | Refered to the proper DTD and stylesheet. |
20010829 | JJM | Updated the list of WG members: one person per line in the XML file, for easier updating. |
20010816 | MJH | Replaced a mustUnderstand="1" with mustUnderstand="true". Slight rewording in mu description. |
20010810 | MJH | Merged in RPC fault rules text from Jacek. Added new DataEncodingUnknown fault code to SOAP Fault Codes section. Added editorial notes about introduction of new fault code namespace for RPC. |
20010809 | MJH | Merged in "mustHappen" descriptive text from Glen and Noah. |
20010809 | MJH | Fixed language around "default" values of attributes. |
20010809 | MJH | Removed HTTP extension framework, added editorial note to describe why. |
20010808 | MJH | Added Infoset "specified" property text from Chris. |
20010808 | MJH | Removed assumption 4 from version transition appendix. |
20010808 | MJH | Added reference to SOAP 1.1 specification to references section, removed SOAP 1.1 author list from acknowledgments section. |
20010807 | MJH | Converted specification from HTML to XML conforming to W3C XMLSpec DTD. Numerous resulting formatting changes. |
20010720 | MJG | Applied Infoset terminology to sections 1, 2, 3 and 4. |
20010629 | MJG | Amended description of routing and intermediaries in Section 2.1 |
20010629 | JJM | Changed "latest version" URI to end with soap12 |
20010629 | JJM | Remove "previous version" URI |
20010629 | JJM | Removed "Editor copy" in <title> |
20010629 | JJM | Removed "Editor copy" in the title. |
20010629 | JJM | Added "Previous version" to either point to SOAP/1.1, or explicitly mention there was no prior draft. |
20010629 | JJM | Pre-filed publication URIs. |
20010629 | JJM | Incorporated David's suggested changes for the examples in section 4.1.1 to 4.4.2 |
20010629 | JJM | Fixed some remaining typos. |
20010629 | MJH | Fixed a couple of typos. |
20010628 | MJG | Made various formatting, spelling and grammatical fixes. |
20010628 | MJG | Moved soap:encodingStyle from soap:Envelope to children of soap:Header/soap:Body in examples 1, 2, 47, 48, 49 and 50 |
20010628 | MJG | Changed text in Section 2.1 from 'it is both a SOAP sender or a SOAP receiver' to 'it is both a SOAP sender and a SOAP receiver' |
20010628 | MJG | Fixed caption on Example 24 |
20010628 | MJH | Fixed a couple of capitalisation errors where the letter A appeared as a capital in the middle of a sentence. |
20010628 | MJH | Updated figure 1, removed ednote to do so. |
20010622 | HFN | Removed the introductory text in terminology section 1.4.3 as it talks about model stuff that is covered in section 2. It was left over from original glossary which also explained the SOAP model. |
20010622 | HFN | Moved the definition of block to encapsulation section in terminology |
20010622 | HFN | Removed introductory section in 1.4.1 as this overlaps with the model description in section 2 and doesn't belong in a terminology section |
20010622 | HFN | Removed reference to "Web Characterization Terminology & Definitions Sheet" in terminology section as this is not an active WD |
20010622 | HFN | Added revised glossary |
20010622 | HFN | Added example 0 to section 1.3 and slightly modified text for example 1 and 2 to make it clear that HTTP is used as a protocol binding |
20010622 | MJG | Added http://example.com/... to list of application/context specific URIs in section 1.2 |
20010622 | MJG | Updated examples in section 4.1.1 to be encodingStyle attributes rather than just the values of attributes |
20010622 | MJG | Added table.norm, td.normitem and td.normtext styles to stylesheet. Used said styles for table of fault code values in section 4.4.1 |
20010622 | MJG | In Appendix C, changed upgrade element to Upgrade and env to envelope. Made envelope unqualified. Updated schema document to match. |
20010622 | MJG | Moved MisunderstoodHeader from envelope schema into seperate faults schema. Removed entry in envelope schema change table in Appendix D.2 that refered to additon of said element. Modified example in section 4.4.2 to match. Added reference to schema document to section 4.4.2 |
20010622 | MJH | Added binding as a component of SOAP in introduction. Fixed a couple of typos and updated a couple of example captions. |
20010622 | MJG | Made BNF in section 6.1.1 into a table. |
20010622 | MJG | Made BNFs in section 5.1 clause 8 into tables. Added associated 'bnf' style for table and td elements to stylesheet |
20010622 | MJG | Amended text regarding namespace prefix mappings in section 1.2 |
20010622 | MJG | Added link to schema for the http://www.w3.org/2001/06/soap-upgrade namespace to Appendix C. Updated associated ednote. |
20010622 | MJG | Added reference numbers for XML Schema Recommendation to text prior to schema change tables in Appendix D.2 and linked said numbers to local references in this document |
20010622 | MJG | Reordered entries in schema change classification table in Appendix D.2 |
20010622 | MJG | Changed type of mustUnderstand and root attributes to standard boolean and updated schema change tables in Appendix D.2 accordingly |
20010622 | JJM | Manually numbered all the examples (53 in total!) |
20010622 | JJM | Added caption text to all the examples |
20010622 | JJM | Replaced remaining occurrences of SOAP/1.2 with SOAP Version 1.2 (including <title>) |
20010621 | HFN | Added ednote to section 4.2.2 and 4.2.3 that we know they have to be incorporated with section 2 |
20010621 | HFN | Added version transition appendix C |
20010621 | HFN | Applied new styles to examples |
20010621 | HFN | Changed term "transport" to "underlying protocol |
20010621 | HFN | Changed example URNs to URLs of the style http://example.org/... |
20010621 | MJH | Updated the Acknowledgements section. |
20010621 | JJM | Added new style sheet definitions (from XML Schema) for examples, and used them for example 1 and 2. |
20010621 | JJM | Incorporated David Fallside's comments on section Status and Intro sections. |
20010620 | HFN | Changed the status section |
20010620 | HFN | Changed title to SOAP Version 1.2 and used that first time in abstract and in body |
20010620 | HFN | Removed question from section 2.4 as this is an issue and is to be listed in the issues list |
20010620 | HFN | Moved change log to appendix |
20010615 | JJM | Renamed default actor to anonymous actor for now (to be consistent) |
20010615 | JJM | Fixed typos in section 2 |
20010614 | JJM | Updated section 2 to adopt the terminology used elsewhere in the spec. |
20010613 | MJH | Updated mustUnderstand fault text with additions from Martin Gudgin. |
20010613 | MJH | Added schema changes appendix from Martin Gudgin. |
20010613 | MJH | Added mustUnderstand fault text from Glen Daniels. |
20010612 | MJH | Fixed document <title>. |
20010612 | MJH | Moved terminology subsection from message exchange model section to introduction section. |
20010612 | MJH | Fixed capitalisation errors by replacing "... A SOAP ..." with "... a SOAP ..." where appropriate. |
20010612 | MJH | Removed trailing "/" from encoding namespace URI. |
20010612 | MJH | Fixed links under namespace URIs to point to W3C space instead of schemas.xmlsoap.org. |
20010612 | MJH | Removed some odd additional links with text of "/" pointing to the encoding schema following the text of the encoding namespace URI in several places. |
20010611 | MJH | Incorporated new text for section 2. |
20010611 | JJM | Changed remaining namespaces, in particular next. |
20010609 | JJM | Changed the spec name from XMLP/SOAP to SOAP. |
20010609 | JJM | Changed the version number from 1.1 to 1.2. |
20010609 | JJM | Changed the namespaces from http://schemas.xmlsoap.org/soap/ to http://www.w3.org/2001/06/soap-. |
20010609 | JJM | Replaced the remaining XS and XE prefixes to env and enc, respectively. |
20010601 | MJH | Updated the examples in section 1, 6 and appendix A with text suggested by Martin Gudgin to comply with XML Schema Recommendation. |
20010601 | JJM | Updated the examples in section 4 and 5 with text suggested by Martin Gudgin, to comply with XML Schema Recommendation. |
20010531 | HFN | Removed appendices C and D and added links to live issues list and separate schema files. |
20010531 | MJH | Added this change log and updated schemas in appendix C to comply with XML Schema Recommendation. |
The encoding schema has been updated to be compliant with the XML Schema Recomendation[4][5]. The table below shows the categories of change.
Class | Meaning |
---|---|
Addition | New constructs have been added to the schema |
Clarification | The meaning of the schema has been changed to more accurately match the specification |
Deletion | Constructs have been removed from the schema |
Name | The schema has been changed due to a datatype name change in the XML Schema specification |
Namespace | A namespace name has been changed |
Semantic | The meaning of the schema has been changed |
Style | Style changes have been made to the schema |
Syntax | The syntax of the schema has been updated due to changes in the XML Schema specification |
The table below lists the changes to the encoding schema.
Class | Description |
---|---|
Namespace | Updated to use the http://www.w3.org/2001/XMLSchema namespace |
Namespace | Value of targetNamespace attribute changed to http://www.w3.org/2001/06/soap-encoding |
Semantic | Changed type of the root attribute from restriction of boolean that only allowed 0 or 1 as lexical values to the standard boolean in the http://www.w3.org/2001/XMLSchema namespace. The lexical forms 0, 1, false, true are now allowed. |
Addition | Added processContents="lax" to all element and attribute wildcards |
Syntax | Changed base64 simple type to be a vacuous restriction of the base64Binary type in the http://www.w3.org/2001/XMLSchema namespace |
Syntax | Updated all complex type definitions with simple base types to new syntax |
Syntax | Added <xs:sequence> to all complex type definitions derived implicitly from the ur-type |
Syntax | Added <xs:sequence> to all named model group definitions |
Deletion | Removed the timeDuration datatype |
Addition | Added duration datatype derived by extension from the duration datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Deletion | Removed the timeInstant datatype |
Addition | Added dateTime datatype derived by extension from the dateTime datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added gYearMonth datatype derived by extension from the gYearMonth datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added gYear datatype derived by extension from the gYear datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added gMonthDay datatype derived by extension from the gMonthDay datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added gDay datatype derived by extension from the gDay datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added gDay datatype derived by extension from the gDay datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Deletion | Removed the binary datatype |
Addition | Added hexBinary datatype derived by extension from the hexBinary datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added base64Binary datatype derived by extension from the base64Binary datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Deletion | Removed the uriReference datatype |
Addition | Added anyURI datatype derived by extension from the anyURI datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added normalizedString datatype derived by extension from the normalizedString datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Addition | Added token datatype derived by extension from the token datatype in the http://www.w3.org/2001/XMLSchema namespace. |
Clarification | Added explicit namespace="##any" to all element and attribute wildcards which did not previously have an explicit namespace attribute |
Style | Where possible comments have been changed into annotations |