View
216
Download
0
Category
Preview:
Citation preview
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 1/28
An OASIS White Paper
Design Guide for specifications built on the DevicesProfile for Web Services
By Dan Driscoll (Microsoft Corporation)
For OASIS
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 2/28
Last revision 3 May 2012 2
OASIS (Organization for the Advancement of Structured Information Standards) is a not-for-profit, international consortium
that drives the development, convergence, and adoption of e-business standards. Members themselves set the OASIS technical
agenda, using a lightweight, open process expressly designed to promote industry consensus and unite disparate efforts. The
consortium produces open standards for Web services, security, e-business, and standardization efforts in the public sector and
for application-specific markets. OASIS was founded in 1993. More information can be found on the OASIS website at
http://www.oasis-open.org.
The OASIS Web Services Discovery and Web Services Devices Profile (WS-DD) Technical Committee produces the SOAP-over-
UDP, Web Services Discovery (WS-Discovery), and Devices Profile for Web Services (DPWS) specifications for communicating
SOAP over UDP, providing a lightweight dynamic discovery protocol to locate web services, and profiling existing Web Services
protocols to be suitably implemented on devices, respectively. More information can be found on the OASIS WS-DD website at
http://www.oasis-open.org/committees/ws-dd/.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 3/28
Design Guide for specifications built on the Devices Profile for Web Services
Table of Contents
Introduction...................................................................................................... 5
Goals and audience....................................................................................... 5
Additional materials ....................................................................................... 5
Overview.......................................................................................................... 5
Terminology .................................................................................................... 6
Section 1: Abstract protocol design on DPWS............................................ 7
Terminology for this section ......................................................................... 7
Organizing services on a device.................................................................. 7
Organizing operations within a service ....................................................... 9Adding parameters to operations .............................................................. 11
Event delivery and filtering ......................................................................... 13
Bindings ......................................................................................................... 14
Service and device types ............................................................................ 15
Faults ............................................................................................................. 16
Abstract service design guidelines ............................................................ 16
Section 2: Creating a specification from an abstract protocol ................. 18
Anatomy of a specification built on DPWS............................................... 18
Referencing DPWS...................................................................................... 19
Choosing a namespace .............................................................................. 21
Section 3: Creating a WSDL/XSD .............................................................. 23
Step 1: Organize abstract protocol definition........................................... 23
Step 2: Copy the WSDL template ............................................................. 23
Step 2: Convert services to WSDL portTypes ......................................... 24
Step 3: Add portTypes for WS-Discovery types ...................................... 25
Step 4: Convert method calls to WSDL operations ................................ 25
Step 5: Add WSDL messages ................................................................... 26
Step 6: Convert types into XSD types ...................................................... 26
Step 7: Define XSD elements .................................................................... 27
Step 8: Include the namespace ................................................................. 28
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 4/28
Last revision 3 May 2012 4
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 5/28
Design Guide for specifications built on the Devices Profile for Web Services
Introduction
The Devices Profile for Web Services (DPWS) assembles and constrains generic Web Services
specifications so devices can easily and uniformly implement functionality common across many different
device classes, such as embedded sensors, kitchen appliances, printers, and even device emulatorsrunning on servers.
Although DPWS defines discovery and metadata operations common to all devices, it does not define the
operations specific to any particular device class. Instead, it provides a toolkit of profiled optional
functionality that is available from many DPWS implementations, and which may be used to construct
sophisticated device control specifications.
This document provides design guidance for specifications that rely on DPWS, and provides direction on
how to reference and use the various components inside it.
Goals and audience
This guide is intended to provide guidance and best practices in designing a specification that referencesDPWS. It is intended primarily for specification authors building public device control protocols. This
document focuses on the most common uses for DPWS.
This guide is not intended to provide a comprehensive set of requirements and recommendations for
referencing DPWS, and is specifically not designed to address unusual or exotic uses.
Additional materials
The OASIS Web Services Discovery and Web Services Devices Profile (WS-DD) Technical Committee
has produced additional materials describing the DPWS and the other specifications standardized
alongside it (WS-Discovery and SOAP-over-UDP). Business- and technical-level whitepapers on all of
these specifications are available from the WS-DD TC.
A companion document to this guide is the DPWS Toaster Example Version 1.0 specification. The
example specification is annotated with recommendations and best practices and can serve as an
additional resource in producing a specification built on DPWS.
Overview
This document is divided into three sections, each covering one of the aspects of protocol and
specification design. The first section provides direction on abstract protocol design, and can be used to
best identify which parts of DPWS can best be used to solve problems for a particular device class.
The second section describes the process of building normative text that references DPWS and uses the
protocol elements designed earlier.
The last section provides concrete steps for transforming a set of abstract protocol definitions into a
WSDL and XSD file suitable for most Devices Profile stacks.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 6/28
Last revision 3 May 2012 6
Terminology
DPWS The Devices Profile for Web Services (DPWS) assembles and constraints
generic Web Services specifications.
Specification In this document, the term specification refers to a protocol specification
specific to a particular device class (e.g., toasters). The DPWS Toaster
Example Version 1.0 is a sample specification built on DPWS.
Client A client is a network endpoint that implements the CLIENT role as defined in
DPWS.
Device A Device consists of a DEVICE and zero or more HOSTED SERVICEs, as defined
in DPWS. DPWS distinguishes the DEVICE service as a special service; this
guide refers to a Device as a collection of services related to a single physical
instance or logical grouping (such as an emulator).
Host Service Synonymous with the DEVICE service
Hosted Service A Hosted Service is a network endpoint that implements the HOSTED SERVICE
role as defined in DPWS.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 7/28
Design Guide for specifications built on the Devices Profile for Web Services
Section 1: Abstract protocol design on DPWS
The most challenging part of designing a network protocol—even one built on existing frameworks like
DPWS—is defining the structure, contents, and behaviors of the messages sent to and from the device.
Designing the right set of operations is a matter of finding the balance between feature requests,implementation constraints, similar protocols, and technology available in devices.
These factors depend heavily on the environment in which a solution is written. This environment varies
across device classes, and it also varies across individual protocol solutions in each class. Examining
and accommodating these factors is left as an exercise to the reader.
However, there are some general guidelines and best practices that cut across all solutions built on
DPWS, and this section describes those in detail. They are not a substitute for informed protocol design,
but can be used to supplement it.
Terminology for this section
This terminology is used primarily in this section, and in Section 3.
Service A DPWS Hosted Service that exposes functionality to network-attached
clients.
Service type A name that defines a set of operations. A service may implement more than
one type.
Operation A one-way or two-way exchange of messages between a client and a service.
Message A SOAP message with a header and a body. The header contains addressing
and other information, and the body contains parameters.
Parameter Content carried inside a message body. Multiple parameters may bestructured and carried inside a single message.
Organizing services on a device
DPWS describes a basic model for a device: a Host (or “DEVICE”) service handles all discovery and
metadata traffic on the device, and one or more Hosted Services handle control messages specific to a
particular class of devices. Attributes describing those Hosted Services are listed inside the device’s
metadata and can be accessed by client software before connecting to each service.
The organization of Hosted Services within a device is largely unconstrained by DPWS. A device mayhave zero or more services, and those services each have one or more types that describe their
behavior. A single device may contain multiple services; those services may have identical types, they
may have different types defined by a single specification, and they may be of different types defined by
different specifications.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 8/28
Last revision 3 May 2012 8
Figure 1 shows a sample service arrangement on a hypothetical toaster/printer device. The first service
implements the Toasting service defined in the attached Toaster example specification. The second
service implements this type and a Printing type—ostensibly since that service can perform both toasting
and printing duties. The last service is a Safety service, as defined in the Toaster specification.
Often, a specification will only define a single service type. This is the most typical solution and is
absolutely acceptable. The attached Toaster example shows a more complex topology with two different
service types, but this complexity is included to illustrate how to properly constrain service composition.
Specification authors should expect that implementers will want to combine services for different device
classes in the same DPWS solution. This composability is one of the core benefits of DPWS and most
specifications are written with this pattern in mind.
In all cases, functionality encapsulated in a particular type should be cohesive and should reflect the
natural breakdown of device services. Individual operations inside a service can be defined as optional,
and so it is usually unwise to artificially split a set of cohesive operations down further into mandatory and
optional components.
Recommendations on organizing services in a device
1. Consider how devices in your class are typically organized and build a structural service model to
best accommodate those designs.
2. Define types that encapsulate cohesive sets of functionality.
Host Service
Hosted Service
Type: Toasting
Hosted Service
Type: Toasting
Type: Printing
Hosted Service
Type: Safety
Figure 1: Example service topology
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 9/28
Design Guide for specifications built on the Devices Profile for Web Services
3. Do not artificially split types into mandatory and optional sections; instead, make individual
operations inside a type optional.
4. Expect that implementers will want to combine your services with services from other
specifications on a single device.
Organizing operations within a service
Once an approximate set of functionality is mapped to a service type, operations inside that service may
be defined for specific protocol behaviors. These operations are at the core of the protocol and typically
result in far more discussion, iteration, and scrutiny than any other part of the specification. The abstract
behaviors that underpin these operations are completely dependent on the application domain, and by
definition cannot be described generically; although, generic interface design guidance is applicable to
Web Services protocols.
This remainder of this section provides an overview of the various styles of operations inside those
services, the parameters those operations may contain, and considerations for producing a robust set of
operation definitions.
Types of operations
DPWS provides facilities for three basic classes of operations:
One-way operations, which consist of a message from the client to the server, and no response.
Two-way operations, which consist of a message from the client to the server and a matching
response from the server to the client.
Event operations, which consist of a message from the server to the client, and no response.
Detailed descriptions for these are included below. A fourth operation class, two-way event operations
(also called Solicit-Response operations), exists but is not widely supported. It is not covered in this
document.One-way operations are lightweight but do not result in a reliable receipt of the message; if a device
consumes a one-way message but fails to process it for any reason, the device is not obligated to
indicate that failure to the client. The client therefore cannot assume that one-way messages are
successfully processed. This one-way pattern is often used for non-critical update messages where
timeliness and light weight is more important than reliable transmission. An example is a client that
periodically sends a temperature reading to an HVAC device; if the temperature is sent every few
minutes, it may not be critical to indicate receipt of every message.
Two-way operations are heavier than one-way operations but provide a channel for response data, and
can also carry enough data to indicate that request was successfully (or unsuccessfully) processed.
Service definitions are often comprised primarily of two-way operations as the response message is used
to carry parameters, an extensibility point, or solely to indicate that the operation completed successfully.
Event operations are unique in allowing a service to send an unsolicited message to a client. These
operations are, just like the one-way and two-way operations, defined by the specification building on
DPWS, although WS-Eventing provides a mechanism for the client and service to negotiate and maintain
a subscription relationship to allow event messages to be sent. Event operations are one-way and do not
provide a way for the client to send parameters back to the service.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 10/28
Last revision 3 May 2012 10
Selecting the right operation
Figure 2 illustrates the flow for selecting the operation type for a particular protocol behavior.
The majority of messages in a typical specification built on DPWS are two-way messages, as the
response message provides a receipt that the request was received, and also provides a channel for
returned parameters. A protocol author building on DPWS should consider two-way operations to be the
default choice for message exchanges initiated by a client.
In cases where the response message is genuinely unnecessary, a one-way operation is more efficient.
Lastly, message exchanges initiated by the device should be defined as events.
Recommendations on organizing operations within a service
1. Use the flow chart in Figure 2 to determine whether to make each operation one-way, two-way, or
an event.
2. When deciding whether to make an operation one-way or two-way, weigh the performanceadvantages of the one-way message against the guaranteed receipt of the two-way message.
Who
initiates
this
messageIs a
response
message
necessary?
Event
Client
Device
One-way
Two-way
No
Yes
Figure 2: Flow chart for selecting operation type
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 11/28
Design Guide for specifications built on the Devices Profile for Web Services
Adding parameters to operations
Once the individual operations have been defined, the next step is to define the structure for parameters
to be transmitted inside the operation’s messages. These parameters are the sole contents of the SOAP
Bodies for these messages, and may be as simple or complex as necessary.
The task of populating messages with parameters is specific to the application domain of the protocolbuilt on DPWS. This section does not provide guidance on choosing an appropriate structure; it is
expected that the protocol author will have an approximate idea of how parameters fit together and are
attached to each device behavior or message. Instead, this section touches on the tools available to
define and represent those parameters inside messages.
XML Schema constructs available for defining parameters
In theory, the XML inside each message body may be exotic and nuanced as long as it can be crisply
described within XML Schema and normative specification text. In reality, some of the more unusual
XML constructions are not uniformly implemented and may not be very interoperable. This section (and
Section 3) highlights some of the more common patterns, but it does not provide a list of “safe” or
“unsafe” elements, as the line between these is blurry and can move over time. In general, concretedefinitions (e.g., complexType+sequence ) are better supported than abstract and inherited definitions
(e.g., complexType+model ), and underived base datatypes (string ) are better supported than heavily
derived datatypes (ENTITY ).
Many of the most common XML Schema (XSD) items can be divided into two categories:
Structural definitions, which allow parameters to be grouped into trees, lists, sequences,
attributes, and so forth. These are defined in XML Schema Part 1.
Datatypes, which define the type of data contained inside a specific text field. Examples include
integer, string, and date/time. These are defined in XML Schema Part 2.
Protocol authors can use these two categories of XSD items to create parameter structures inside
messages. Structural definitions can be used to create schema analogues to C/C++ structures, anddatatypes can be used to create fields for strings, integers, identifiers, etc.
The use of XSD to define message content is best shown by example. See the companion DPWS
Toaster Example Version 1.0 specification for XSD and WSDL.
Binary attachments
One special class of parameter is the binary attachment. DPWS describes the use of the Message
Transmission Optimization Mechanism (MTOM) to attach binary streams to SOAP messages. These
streams can be used to move raw data, such as images, packed binary commands, or streaming
audio/video content.
Binary streams are represented by the base64Binary XSD type. All base64Binary fields are attachments,and adding them to the message will result in binary data being appended to the SOAP envelope. Even
though the binary data is not included directly in the SOAP, the base64Binary field should be included in
a natural position inside the message as though the data were embedded directly.
Messages may contain multiple base64Binary fields although they are moved serially and the first
attachment must be closed before subsequent attachments can begin. Typically (although not always)
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 12/28
Last revision 3 May 2012 12
DPWS stacks allow applications to perform streamed reads and writes to attachment streams, as the
stream content may sometimes be too large to fit into memory.
Extensibility points
An important characteristic of nearly every Web Services specification is the presence of extensibility
points. These points allow implementers and future users of the protocols to add their own informationinto existing messages. Although specific extensibility points have varying levels of utility, extensibility
points in general are critical to the long-term usability of a protocol.
Extending a WSDL by adding new messages, operations, and portTypes is accomplished with a well-
defined namespace revision policy. This allows future revisions of the specification to retroactively add
new messages wholesale, and is described in greater detail in Section 3.
Extending existing messages by inserting new elements and attributes into existing structures is
accomplished by manually inserting extensibility points into the message definitions when first defined.
Specifically, the <xs:any> extensibility point allows insertion of new element data, and <xs:anyAttribute>
allows insertion of new attributes.
Most complex structure definitions (e.g., complexType+sequence ) will contain an extensibility point at theend. A good general policy is to include <xs:any> at the end of every complex type definition, although it
is not strictly necessary and may be omitted when no implementers could conceivably have any data they
ever want to add to contribute to the purpose of the particular structure. Care should be taken to ensure
at least one <xs:any> extensibility point is available inside the SOAP Body of every message (even those
which do not carry parameters).
In contrast, many structures and elements do not contain <xs:anyAttribute>. Attribute extensibility points
are most often added when the interpretation of the content inside the element in question could be
overridden by a new specification.
In the case of <xs:any> and <xs:anyAttribute>, adding extensibility points generally does not incur any
cost above the space taken in the XSD and the number of fields and parameters in generated code.
When in doubt, add <xs:any> to all structures.
A quick note on WSDL style
Readers familiar with WSDL may note that there are several styles of encoding parameters inside
messages. This guide describes the use of a common and interoperable style (wrapped document-literal)
and does not address the others. All readers should consider the style to be immaterial to this
discussion, as this section addresses parameterization nested inside the elements affected by differences
in style. The concrete steps in Section 3 will result in WSDL written in wrapped document-literal style.
Recommendations on adding parameters to operations
1. Choose concrete structural definitions (e.g., complexType+sequence ) and underived base types(e.g., string, anyURI, etc.) for best interoperability.
2. Build ComplexType definitions for structures and reuse these across messages where
appropriate.
3. Consider using xs:anyURI for any identifier fields (job IDs, etc.) instead of xs:string.
4. Use xs:base64Binary to add binary attachment data to a message.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 13/28
Design Guide for specifications built on the Devices Profile for Web Services
5. Add <xs:any> to all XSD structure definitions, except where clearly unnecessary.
Event delivery and filtering
DPWS applications often include support for events, unsolicited messages sent from the device back to
the client. The structure of event messages is defined in the same way as forward control messages;
WSDL and XSD are used to describe the message and its contents.
In addition to the directionality of the message exchange, events differ from forward control messages in
four important ways:
Clients use the WS-Eventing protocol to manage the lifetime and filtering criteria of the
subscription for event messages.
Events are almost universally one-way messages, as two-way events (also called solicit-
response events) are not generally interoperable.
The number of messages often differs from client-initiated forward control messages. For
instance, a client will usually only send a single message to a single device; in contrast, a device
sending events may send the same message to many different subscribed clients. Thissometimes results in a different programming model for events than for other messages.
Clients are often inaccessible due to network topology, firewall settings, or because the client
dropped offline. This is a problem in all DPWS scenarios, but is particularly troublesome in
eventing because inaccessible clients can cause a delay in event delivery to other clients.
For these reasons, protocol authors should take care when designing events, and should be particularly
cautious that the events do not result in overly burdensome wire traffic or programming models. The
following subsections describe ways to accommodate these differences. Prior sections on designing
WSDL and XSD for control messages are otherwise applicable.
Reliability and latency in events
Because events are generally one-way messages, they do not offer the transmission receipt guaranteed
by two-way messages. A service cannot be sure that any clients successfully processed the events that
it sent. Accordingly, events should not be used to carry critical data; in cases where an event is used to
present results from a long-running operation, the event can be used merely to inform a client that results
are available. The client can then retrieve the results with a traditional two-way operation, guaranteeing
the data is not lost in a dropped event.
When using events, there is also a risk of clients being inaccessible because of network topology, firewall
settings, or because the client simply dropped offline. If the device is obligated to send events to many
different clients, a few inaccessible clients can result in significant delays delivering the event to other
clients. This problem can be somewhat ameliorated with intelligent filtering, but in general, timely delivery
is often very difficult to guarantee in eventing scenarios.
Event filtering
WS-Eventing provides a mechanism for clients to express filtering criteria for events they would like to
receive. The service (to which the client is subscribed) may then send messages that meet the filtering
criteria specified in the subscription. WS-Eventing does not specify any filtering criteria; it only provides a
location for that criteria to be defined and used.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 14/28
Last revision 3 May 2012 14
Note that even though many clients may be subscribed for a certain message, the service is not obligated
to send a message to every subscribed client. The filter is merely a way for the client to specify that it is
interested only in certain messages.
DPWS defines a filter that may be reused by applications building on DPWS; this filter allows clients to
specify acceptable WS-Addressing Action values. Action is a common filtering criterion, as it relates
directly to the type of message which will be received. It does not provide more sophisticated (andheavier) filtering semantics, such as the ability to perform an XPath query on the entire message body.
In many cases, the DPWS Action filter is sufficient for clients to meaningfully limit the types of events the
service will send. In other cases (particularly those with a substantial number of subscribed clients and
event traffic), the message content varies enough that additional or different filtering is necessary. There
are a number of options in these cases:
Retain the Action filter, and divide events into more granular events. For instance, the attached
toaster example includes general events suitable for administrators and users, and specific job
events suitable primarily for users. This allows administrators to avoid receiving chatty job-
specific traffic.
Retain the Action filter, but allow the service to filter on additional information. Because the
service is not obligated to send events to every client, it may limit event messages to certain
classes of clients, or to a specific client. For instance, a specific message exchange (or
“session”) may be related by a single identifier; the client may supply this identifier in its
Subscribe message and in messages which may later trigger events; the service may then send
events for a specific operation only back to the client that supplied the identifier.
Define a new filter specific to the application. Although this can be effective in solving complex
filtering problems, it may also be a burden to implementers whose DPWS toolkits do not support
pluggable WS-Eventing filters. It is also preferable to keep the filtering criteria as simple as
possible.
Recommendations on defining events
1. Do not define messages for managing event subscriptions (e.g., Subscribe, Unsubscribe). WS-
Eventing provides these for you.
2. Do not rely solely on events to carry critical data. Instead, provide access to that data through
traditional two-way messages, and use events as one of the ways to inform clients that data is
available.
3. Use the sections on one-way and two-way forward control messages as a guide to define the
structure of each event message.
Bindings
Any protocol built on DPWS is required to support a basic protocol binding of SOAP 1.2 over HTTP. This
binding is very common and is sufficient for most protocols. Protocol authors are encouraged to rely
solely on SOAP 1.2 over HTTP.
In certain (advanced) cases, additional protocol bindings are necessary: such as SOAP 1.1 over HTTP,
or over another base protocol entirely. Both DPWS and WS-Discovery advertise service capabilities in
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 15/28
Design Guide for specifications built on the Devices Profile for Web Services
terms of abstract portTypes, making it cumbersome to determine which bindings are supported by a
service advertising a specific set of abstract operations.
There are two problems protocol authors should consider in extending beyond SOAP 1.2 over HTTP:
1. Clients must know which binding(s) they can use when contacting a service. This may be defined
in the specification (e.g., “a SERVICE MUST support both the SOAP 1.1 and SOAP 1.2 binding”)
or it may be discovered at runtime via WSDL or other mechanisms (e.g., an extensible element in
the device’s metadata). Either way, this behavior must be defined.
2. Because DPWS requires the default binding on every service endpoint, every service that
supports a new binding must also concurrently support the default DPWS binding. Depending on
the specifics of the new binding, it can be difficult to find widespread Web Services stack
implementations that can handle the new and the default DPWS binding.
Recommendations on defining bindings
1. Rely on the default DPWS SOAP 1.2 over HTTP binding if possible.
Service and device types
DPWS requires every service to have a type; this type is used by clients to determine which services they
are able to use. Additionally, the DPWS Host service advertises a set of types so the device can be
discovered using WS-Discovery queries with specific type criteria. In general, service types cannot be
reused at the DPWS Host service because the Host service does not directly accept the application-
specific control messages described by the service type.
Instead, the DPWS Host service advertises a dummy type (not directly associated with any callable
operations) which shows that the device contains related services. For example, a device that advertises
the ToasterDevice type will host at least ToastingService services, and possibly also SafetyService
services. The requirements between the device-level type and the service-level types can be as complex
as necessary; in this case, every toaster is required to have at least one ToastingService but is notrequired to have any SafetyService services. A device that contains a single SafetyService but no
ToastingService is not considered a toaster, and so it cannot advertise the ToasterDevice type.
Often, only a single device-layer type is required even if many different service types are defined. In
cases where there is very little cohesion between function of various services, consider splitting them into
separate protocols before defining distinct device-layer types for each.
In general, applications built on DPWS are designed to be composable so that multiple solutions can be
built into a single piece of hardware. It would be technically possible to build a combination toaster and
printer which advertised both ToasterService services and PrinterService services. Correspondingly, this
device would have to advertise the correct device-layer types, such as ToasterDevice and PrinterDevice.
For this to be possible, the ToasterDevice type cannot preclude the presence of unrelated services on the
device.
In cases where a single device type is chosen, DPWS Appendix C can be used to programmatically
couple all service types to the single device type. If a more complex device topology is necessary, the
relationship between types can be described in written normative text or in more sophisticated type
description languages.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 16/28
Last revision 3 May 2012 16
Recommendations on service and device types
1. Define a device-layer type for related groups of service functionality.
2. Use DPWS Appendix C to bind service-layer types with a device type.
3. When necessary, express more complex type relationships with normative text or a type
description language.
Faults
In addition to defining the structure of messages and successful responses, protocol authors should
devote attention to error conditions and, in particular, SOAP Faults.
SOAP Faults are mechanisms that services can use to communicate specific failure data. Many generic
faults are defined by underlying specifications (e.g., WS-Addressing, WS-Eventing, etc.), and these may
be reused by stack implementers to communicate general failures, such as an improperly addressed
message.
In certain cases, a client can take meaningful action when certain errors occur. For instance, if a Toaster
client were unable to begin toasting because the service is already toasting, it could conceivably wait forthe current toast to complete before scheduling a new one. Enabling this fallback logic would require the
toaster service to communicate specific information in the error—the fact that it is already toasting—
because a generic error message would not convey enough information for the client to know to wait and
retry later.
In other cases, the failure may not be particularly meaningful but the error may be useful for the client
software to present to a user or log to a file. In these cases, a generic fault is sufficient as long as it
carries descriptive detail inside the fault.
The concrete steps in Section 3 describe how to add a fault to a protocol definition.
Recommendations on faults1. Define faults to express error conditions where a client could take meaningful action.
2. Do not redefine faults in underlying specifications, such as “Endpoint Unavailable.”
3. Do not define faults simply to carry descriptive text; use existing faults and encourage
implementers to add their own (possibly pre-defined) descriptive text.
Abstract service design guidelines
The preceding subsections provide tools available to specifications authors to create an abstract protocol
definition. These tools provide little guidance on how to arrange various protocol components, as this is
heavily dependent on the application domain.Instead, protocol authors are encouraged to seek out generic design guidance for Web Services (or other
remote method invocation interfaces), and any advice for designing protocols for resource-constrained
devices. A short list of common design notes is provided below, as well.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 17/28
Design Guide for specifications built on the Devices Profile for Web Services
Recommendations on abstract service design
1. Services should expose core behavioral concepts without tying too heavily into specific
implementations.
2. Long-running operations should be asynchronous (e.g., have separate start and end wire
operations) and should allow clients to either interrogate the service’s process, or subscribe to
status update events.
3. Clients may have varied reasons for using a device—some may actively use it, and others may
simply monitor its progress. Expect clients will be interested in different subsets of device
functionality.
4. Clients and services should not rely heavily on state information, and should expect that
operations may be invoked out of order except in cases where order is absolutely necessary.
5. Services definitions should expect multiple clients to invoke operations simultaneously.
6. Even if designed as an advanced protocol only intended for state-of-the-art hardware, it is not
uncommon for complex protocols to eventually be implemented on very resource-constrained
devices. Protocol authors should take care to accommodate these devices.
7. Resist the urge to simply transcribe service definitions from other protocol frameworks (e.g.,
UPnP). Most protocol suites have different design idioms which do not always translate well to
DPWS.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 18/28
Last revision 3 May 2012 18
Section 2: Creating a specification from an abstract protocol
Anatomy of a specification built on DPWS
Many specifications built on DPWS (and otherwise) are composed of three parts:
Normative text, a human-readable description of the specification’s rules and behaviors
WSDL/XSD, a machine-readable description of the specification’s messages and types
Non-normative ancillary materials, which provide additional explanations necessary to
understand and use the specification
While it is not strictly necessary to organize material into these three parts, this arrangement is a
commonplace and tested way to separate specification components into cohesive and focused parts.
Normative text
The normative text is the core of a specification, and is typically the most heavily scrutinized componentof the three. Implementers will refer heavily to the text to determine the intent and behavior of each part
of the protocol it defines, and will turn to it when a dispute arises about what is required, recommended,
allowed, or prohibited.
Application-specific specifications (such as the DPWS Toaster example) build heavily on the rules and
behaviors defined in the referenced specifications, such as DPWS; accordingly, the specification does not
need to redefine these rules and concepts, and can instead be focused almost entirely on the domain-
specific operations and behaviors a device will implement.
WSDL/XSD
The Web Services Description Language (WSDL) and XML Schema (XSD) are languages for expressingassociations between names and various messaging primitives like operations and types. WSDL and
XSD files are often included in a specification so the protocol rules (including a subset of the rules defined
in the normative text) are accessible in a machine-readable format. Figure 3 shows the relationship
between a normative text and WSDL in a typical specification.
Figure 3: Relationship between WSDL and normative text
Normative text
WSDL/XSD
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 19/28
Design Guide for specifications built on the Devices Profile for Web Services
WSDL is unable to express even very rudimentary behavioral or sequencing rules, and so it is typically
insufficient to describe an entire protocol.
In most cases, the normative specification text does not fully describe the relationship between the
abstract messaging concepts and the components in the wire message (e.g., the text is unlikely to
explicitly describe the structure of every message) and so the WSDL does cover some parts of the
protocol that the normative text does not address. WSDL can also express runtime-only information(such as extra WS-Policy assertions) and so can be useful outside the context of the normative text.
WSDL is very useful in development tools, and often aids in rapid production of implementations. WSDL
also improves basic interoperability by providing a known machine-readable description of message
formats.
Ancillary materials
The normative specification text and WSDL specify the rules and behavior of devices built to your
specification, and are the authority when resolving inevitable disputes over what is permitted and what is
not. These documents (and specifically, the normative text) should be focused on crisply defining the
behavior, and should not dilute the rules with too much additional material.
Readers nevertheless often need a richer explanation to fully understand the protocol and its meaning.
Ancillary materials (such as white papers, case studies, and examples) are the appropriate location for
explaining domain-specific concepts. Keeping these topics outside the normative text makes it easy to
separate the intended uses from the actual protocol behavior; as the protocol matures its use may extend
beyond the initial examples, but the normative text will always be directly applicable.
Recommendations on specification structure
1. Consider the normative text, WSDL, and ancillary materials to be equally important components
of the entire specification. Providing all three helps keep each focused.
Referencing DPWS
Each component of a specification (normative text, WSDL/XSD, and non-normative material) refers to
lower protocol layers in a different way. This section describes the correct way to bind DPWS into each
section.
Normative references to DPWS
At a minimum, two references are necessary to require DPWS in an implementation:
1. The DPWS document must be referenced. Typically this is dictated by the citation style of the
organization producing the specification.
2. The specification must specifically call out the required roles to be implemented. Often, it is
sufficient to call out that a device must implement the DEVICE role as defined by DPWS.
Additionally, a specification may call out optional components of DPWS. For example, the attached
DPWS Toaster example makes use of events, and so requires the device to implement WS-Eventing, as
profiled in DPWS. While it may be possible to argue that such support is necessary even without a direct
reference, a clear statement that requires support unambiguously informs the implementer that they must
build this component to be compliant.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 20/28
Last revision 3 May 2012 20
WSDL/XSD references to DPWS
The binding between the machine-readable components of a specification (WSDL and XSD) and DPWS
is typically limited to a WS-Policy assertion in the binding section of the WSDL.
Although it is possible to include a reference to the DPWS XSD, this is usually unnecessary; the only
exception is if the specification makes direct use of the types defined in DPWS, and this is very unusual.
Including a reference to the DPWS XSD should otherwise be avoided, as this increases the risk that a
development tool will misinterpret the DPWS structures as being native to the device specification.
The proper way to bind DPWS is to include the WS-Policy assertion (defined in DPWS 1.1 Section 4.4) in
the binding section of the device’s WSDL. Some development tools will skip this assertion (or will not
require this assertion in the first place) but its presence typically does not introduce any problems.
Non-normative descriptions of DPWS and lower-layer protocols
All materials—including ancillary materials—should describe details of lower protocol layers (such as
DPWS) with caution. Although it may initially seem helpful to describe these protocols, there is significant
opportunity to include mistakes or mislead readers. Consider this example of a seemingly innocuous
description:
INCORRECT
The Devices Profile for Web Services (DPWS) defines discovery and metadata behavior common to all devices. It uses
multicast UDP discovery messages (Hello and Probe) to locate devices on the same subnet. It allows a device to express
metadata such as its manufacturer, model name, and connection URL. DPWS also provides events and the ability to move
binary files as attachments.
Even though there is only one factual error in this description (DPWS does not define discovery
messages, WS-Discovery does), it contains many misleading statements:
UDP multicast is not the only way to discover a DPWS device.
Hello and Probe are not the only important WS-Discovery messages.
DPWS metadata defines three URLs (for manufacturer, model, and device presentation page)
and describes endpoint addresses for Hosted Services, but “connection URL” leads the reader to
consider a single connection point for the entire device, which is an oversimplification.
Attachments are binary streams, and may contain data other than file contents.
Instead, consider omitting these details entirely or—if some description is necessary—describe the
abstract properties of these specifications. It is far easier to create an accurate abstract description.
CORRECT
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 21/28
Design Guide for specifications built on the Devices Profile for Web Services
The Devices Profile for Web Services (DPWS) provides common discovery and metadata mechanisms for all device classes,
and assembles additional Web Services technologies so they can be consistently and easily implemented on devices. DPWS
devices can announce themselves or clients can search for them. Clients may retrieve metadata that describes the
characteristics of the device. DPWS also constrains additional technology (such as WS-Eventing and MTOM) that can be
used in control operations specific to a particular device class.
Also consider referring directly to the descriptive materials produced by the WS-DD TC.
Recommendations on referencing DPWS
1. Include citations to DPWS normative material according to the format defined by
2. Refer directly to WS-DD TC white papers and other materials, and only provide abstract
descriptions of lower-layer specifications if additional detail is necessary. Avoid descriptions of
technical or detailed concepts in DPWS or the specifications it references.
Choosing a namespace
Web Services specifications make heavy use of namespaces in XML. Protocols built on DPWS must
declare all wire components (messages, structures, etc.) inside a namespace.
Namespace URI contents
Namespaces in XML are identified by URI, often in the http scheme. These URIs usually reflect the
organization producing the specification—for instance, the OASIS Standard DPWS uses a URI that, when
evaluated as a URL, points to an OASIS web server. Protocol authors building specifications on DPWS
should choose a namespace URI that reflects their organization (a standards body, corporation, or even
an individual).
The value of the URI is not meaningful from a protocol perspective (it merely distinguishes names in
various protocols from each other) and technically, there is no requirement that the URI be a resolvableURL. However, many protocol authors do place an RDDL page at the namespace URL as a
convenience.
Namespace revision policy
In addition to the URI value itself, protocol authors should consider what type of long-term policy will be
associated with this URI. Generally, protocol implementers expect that once a namespace is defined, the
existing contents of that namespace will not be deleted or changed. The addition of new content
(messages, operations, etc.) is more flexible and some specifications clearly call out that future revisions
may reuse an old namespace and add new protocol elements as long as existing ones are not affected.
Defining a namespace policy helps implementers be aware what changes could occur in the future. Italso provides a valuable avenue to add important features to an existing protocol without changing the
content entirely.
Temporary namespace URIs
Often, a protocol is mocked up, prototyped, and discussed before a final namespace can be assigned. In
these cases, it is generally acceptable to use a temporary URI (such as an HTTP-scheme URI with an
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 22/28
Last revision 3 May 2012 22
authority part of example.org ) but great care should be taken to remove and replace these URIs before
the protocol is implemented in products.
Recommendations
1. Choose a namespace URI that reflects the organization producing the specification.
2. Do not define new protocols in the DPWS namespace.
3. Define a namespace revision policy that defines how content may (or may not) be added to the
namespace over time.
4. Remove temporary and placeholder namespace URIs as soon as a proper namespace is
available.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 23/28
Design Guide for specifications built on the Devices Profile for Web Services
Section 3: Creating a WSDL/XSD
This section provides a step-by-step process for constructing WSDL and XSD from an abstract protocol
description. Section 1 in this document helps guide the process of forming a protocol description and
Section 2 describes how that can be codified into normative text and WSDL/XSD; those sections providethe groundwork for the instructions below.
WSDL style
This guide provides steps to author a hand-written WSDL. Although tools exist to produce WSDL from a
programming contract defined in another language, these tools sometimes produce idiomatic
constructions which try to fit the WSDL around the programming platform which produced the code. This
generally results in complex (and sometimes confusing) definitions which are difficult to interpret with
tools on other platforms, or by hand. Because device WSDLs are often consumed on many different
platforms and are sometimes scrutinized manually, it is important that the resulting definition is
unambiguous. Hand-authored WSDL is the best way to achieve this result.
There are also different styles of arranging various elements inside the WSDL. This guide will result inWSDLs in the document-literal style, as this is reasonably interoperable in the device world.
Step 1: Organize abstract protocol definition
Section 1 in this document provides a description of how to assemble a service, how to choose
operations for that service, and how to populate those operations with parameters. That abstract
description should include an approximate mapping of how those services, operations, and parameters all
map to real-world behavior. For example, an abstract description of the StartToasting operation in the
Toaster example would include parameters that may define the duration and type of toasting to occur,
and would also note that a successful response would represent the physical toaster element
successfully starting.Collecting and organizing this abstract description is required to complete step 1. Protocol authors may
find it convenient to transcribe this description into an approximate and annotated interface definition
(e.g., a C++ class) even though this definition will not be read by any tools.
Action : organize protocol elements into services, operations, and parameters.
Step 2: Copy the WSDL template
The next step is to copy this WSDL template into a local file. Some development editors natively support
WSDL files, and many text editors support XML. Advanced functionality in these editors may assist in
making changes to the WSDL but only raw text input is necessary to follow this guide.
When saving this file, it is helpful to choose a name related to the service name. Toaster.wsdl or
ToasterService.wsdl are appropriate names for a Toaster WSDL.
<?xml version="1.0" encoding="utf-8"?>
<definitions
xmlns="http://schemas.xmlsoap.org/wsdl/"
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 24/28
Last revision 3 May 2012 24
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:dpws="http://docs.oasis-open.org/ws-dd/ns/dpws/2009/01"
xmlns:tns="Step 8"
targetNamespace="Step 8">
<types>
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="Step 8"
targetNamespace="Step 8">
<!-- Step 6 -->
<!-- Step 7 -->
</xs:schema>
</types>
<!-- Step 5 -->
<!-- Step 2 -->
<!-- Step 3 -->
</definitions>
Further steps in this guide will replace each named “Step” item with XML or namespaces.
Action : Copy and save this WSDL template into a local file.
Step 2: Convert services to WSDL portTypes
The portType section of a WSDL describes the operations that will comprose a single service. A WSDL
file can contain multiple portType sections, although often it will contain only a single functional service
type, and a dummy definition for WS-Discovery types (Step 3 covers the additional portType).
Replace the <!-- Step --> heading in the WSDL template with <portType> declarations like the one shown
below, and replace the name with one that relates to the service’s purpose.
<portType name="ToasterService">
<!-- Step 4 -->
</portType>
Action : Replace the <!-- Step 2 --> comment in the WSDL. Add a portType section for each service.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 25/28
Design Guide for specifications built on the Devices Profile for Web Services
Step 3: Add portTypes for WS-Discovery types
Section 1 describes the difference between service-layer types and discovery-layer types; defining at
least one WS-Discovery type is recommended.
For each WS-Discovery type, an empty portType is necessary to ensure the name is declared in the
namespace. Replace the <!-- Step 3 --> comment in the WSDL with a portType declaration like the oneshown below.
<portType name="ToasterDevice" />
Optionally, associate each portType with each discovery type using DPWS Appendix C. Add the
dpws:DiscoveryType attribute to the <portType> elements added above, in step 2. Note that the “tns:”
prefix on the ToasterDevice name should be kept as-is; simply replace “ToasterDevice” with the matching
discovery type name.
dpws:DiscoveryType="tns:ToasterDevice"<portType name="ToasterService" ><!-- Step 4 -->
</portType>
Action : Replace the <!-- Step 3 --> comment in the WSDL. Add an empty portType for each WS-
Discovery type. Optionally, add DiscoveryType attributes to bind service portTypes to discovery
portTypes.
Step 4: Convert method calls to WSDL operations
Once the portTypes are mapped, convert each abstract method call into one-way, two-way, or event
operations inside the portType. Operations are composed of input and output messages: one-wayoperations have only an input message; event operations have only an output message; and two-way
messages have both.
Use the template below to add operations to the portType.
…
<operation name="StartToasting">
<input message="tns:StartToastingRequest" />
<output message="tns:StartToastingResponse" />
</operation>
<operation name="AbortToasting">
<input message="tns:AbortToastingRequest" />
</operation>
<operation name="ToastingCompletedEvent">
<output message="tns:ToastingCompletedEvent" />
</operation>
...
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 26/28
Last revision 3 May 2012 26
Action : Replace the <!-- Step 4 --> comment in the WSDL. For each abstract operation in the service,
create an <operation> element inside the <portType> and add <input> and <output> message
references.
Step 5: Add WSDL messages
WSDL contains a <message> definition which is necessary to build a service description, but which does
not have a clear analogue in many other interface definition languages. In this guide, <message>
definitions are added simply to associate parameter structures to operations.
For each input or output message reference added in step 4, add a corresponding <message> definition
following the template below.
...
<message name="StartToastingRequest">
<part name="Body" element="tns:StartToastingRequest" />
</message>
<message name="StartToastingResponse"><part name="Body" element="tns:StartToastingResponse" />
</message>
<message name="AbortToasting">
<part name="Body" element="tns:AbortToasting" />
</message>
<message name="ToastingCompletedEvent">
<part name="Body" element="tns:ToastingCompletedEvent" />
</message>
...
Action : Replace the <!-- Step 5 --> comment in the WSDL. For each message reference in each
portType, add a <message> element.
Step 6: Convert types into XSD types
Once each WSDL message has been defined, steps 6 and 7 will populate them with parameters.
Specifically, step 6 defines structures used to contain multiple parameters.
Begin by inspecting the abstract protocol definition and identifying parameters in each operation. These
parameters can be arranged in lists and trees, similar to C/C++ structures.
Each structure is defined on its own; although XSD allows structures to be defined as nested types, it is
cleaner to define each separately and reference them by name. Each structure can contain fields with
simple types (integer, string, etc.), lists of simple fields, references to other structures, and extensibility
points.
In general, the vast majority of type definitions are complexType+sequence. The sequence compositor is
conceptually similar to a C/C++ struct. Other constructs are available in XML Schema but are left to the
reader to explore.
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 27/28
Design Guide for specifications built on the Devices Profile for Web Services
Individual fields are defined by <element> definitions inside the sequence, and are often modified with
minOccurs and maxOccurs values to define items as optional, or as a list (similar to an array). minOccurs
and maxOccurs both default to 1 if not declared.
References to other structures are by <element> definitions referencing other types. Structures may be
reused in many locations—if a single structure is used in many messages, it may be defined once and
referenced from all other structures where it is used.
Remember to add extensibility points as appropriate in complexType definitions. In cases where a
message contains only a single element (e.g., a SetTemperature operation with a single integer value),
consider defining a complexType that contains the integer and an extensibility point. If a message has no
parameters (e.g., GetTemperature), define a complexType that contains only an extensibility point.
Follow the example below to define <complexType> elements for every parameter structure in the
abstract protocol definition.
Note that all definitions in this section must use the xs namespace prefix.
...
<xs:complexType name="StartToastingRequestType">
<xs:sequence>
<xs:element name="HeatLevel" type="xs:integer" />
<xs:element name="Duration" type="xs:duration" minOccurs="0" />
<xs:element name="ImageToBurn" type="xs:base64Binary" minOccurs="0" />
<xs:any namespace="##other" processContent="lax" />
</xs:sequence>
</xs:complexType>
...
Action : Replace the <!-- Step 6 --> in the WSDL. For each structure type in the abstract protocol, create
a <complexType> definition and fill it with fields, references to other structures, and extensibility points.
Step 7: Define XSD elements
Once the parameter structures have been defined, they must be wrapped in elements before being
referenced in messages.
For every <message> definition created in step 5, create a matching <element> definition that associates
the element name in the <message> with a <complexType> or simple type definition. These <element>
messages are necessary to wrap the message contents in an XML element inside the SOAP Body.
Note that all definitions in this section must use the xs namespace prefix.
...
<xs:element name="StartToastingRequest" type="tns:StartToastingRequestType" />
<xs:element name="StartToastingResponse" type="tns:StartToastingResponseType" />
<xs:element name="AbortToasting" type="tns:AnyElementType" />
<xs:element name="ToastingCompletedEvent" type="tns:AnyElementType" />
...
8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services
http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 28/28
Action : Replace the <!-- Step 7 --> in the WSDL. For each <message> element, add an <element>
definition.
Step 8: Include the namespace
The final step is to add a namespace. The namespace is listed in two locations in the WSDL part, and in
two locations in the XSD part: once to declare the target namespace where every item will be defined,
and once to bind the “tns” (target namespace) prefix to that namespace so that parts of the WSDL can
internally reference other parts. Be sure to replace all four instances.
Directions on selecting a namespace can be found in Section 2 of this guide.
Action : Replace every occurrence of Step 8 in the WSDL with the namespace URI.
Recommended