Web Services Naming Standards A Guide For Enterprise Architects

Web Services Naming Standards
W H I T E P A P E R
A Guide for Enterprise Architects

W H I T E P A P E R
Web Services
The purpose of this document is to provide guidance for an enterprise architect
defining the standardized structure of Web Services names appropriate for the
Naming Standards: enterprise. It explores the issues and best practices involved in defining and
managing enterprise naming standards. The topic is of particular importance because
A Guide for the structuring of the names and the challenges involved in maintaining the
consistency in naming WSDL and XML schema namespaces, services, ports,
operations, and other artifacts in the web services space have a significant impact on
Enterprise Architects the complexity of managing a SOA environment.
November 2009
Copyright TIBCO Software

Inc. All international rights
reserved. Trademarks and
related intellectual property
contained herein are the
property of TIBCO Software
or their respective owners as
cited.
2
Contents
1 Introduction .......................................................................................................................................................... 5
1.1 Setting Expectations ........................................................................................................................................ 5
1.2 Concepts .......................................................................................................................................................... 5
1.3 What’s in a Name? .......................................................................................................................................... 7
1.4 Why are Naming Standards Important? .......................................................................................................... 8
1.4.1 Names are Difficult to Change .............................................................................................................. 8
1.4.2 Name Structures Define Search Strategies ............................................................................................ 8
1.4.3 Name Structures Can Define Routing Strategies ................................................................................... 8
1.5 What needs a name? ........................................................................................................................................ 9
1.6 Purpose and Organization of this Document ................................................................................................. 10
1.7 The FedEx Example ...................................................................................................................................... 10
2 Structured Name Design Principles ................................................................................................................... 11
2.1 Use a General-to-Specific Structure .............................................................................................................. 11
2.2 Employ Hierarchical Naming Authorities ..................................................................................................... 13
2.3 Base Naming on Stable Concepts.................................................................................................................. 13
2.3.1 Domain Concepts................................................................................................................................. 14
2.3.2 Business Processes............................................................................................................................... 14
2.3.3 The Exception to the Rule: Enterprise Identifiers ................................................................................ 14
2.4 Avoid Acronyms and Abbreviations ............................................................................................................. 14
2.5 Distinguish Types from Instances ................................................................................................................. 15
2.6 Plan for Multi-Word Fields ........................................................................................................................... 15
2.7 Use a Distinct WSDL Namespace for Each Service ..................................................................................... 16
3 Applying the Principles:..................................................................................................................................... 16
3.1 Idealized Name Structures............................................................................................................................. 16
3.2 The Functional Context ................................................................................................................................. 17
3.2.1 A Notational Convention: Denoting Internet Domain Names ............................................................. 17
3.3 Address Location Names............................................................................................................................... 18
3.4 WSDL and XSD Namespace Names ............................................................................................................ 20
3.5 WSDL and XSD Filenames .......................................................................................................................... 21
3.6 WSDL Names ............................................................................................................................................... 21
3.7 Schema Locations ......................................................................................................................................... 21
3.8 Operation Names ........................................................................................................................................... 21
3
3.9 SOAP Action Names ..................................................................................................................................... 23

3.10 WSDL Message Names ............................................................................................................................ 23
3.11 XSD Elements Specific to an Interface and an Operation ........................................................................ 24
3.11.1 A Notational Convention: Denoting Namespace Names ................................................................ 24
3.12 XSD Element Specific to an Operation .................................................................................................... 25
3.13 XSD Shared Elements (Common Data Model Elements) ........................................................................ 25
4 Complicating Realities ....................................................................................................................................... 26
4.1 Technology Constraints................................................................................................................................. 26
4.2 Organizational Issues .................................................................................................................................... 27
4.2.1 Naming Authorities.............................................................................................................................. 27
4.2.2 Complex Organizational Structures ..................................................................................................... 27
4.2.2.1 Functional Organizations ........................................................................................................... 27
4.2.2.2 Mixed Functional and Line-of-Business Organizations ............................................................. 28
4.2.2.3 Geographic Distribution ............................................................................................................. 28
4.3 Environments: Values for Address Variables ............................................................................................... 29
4.4 Deployment Flexibility.................................................................................................................................. 30
4.5 Versioning ..................................................................................................................................................... 31
5 Developing Your Standard ................................................................................................................................. 31
4
1 Introduction
The purpose of this document is to provide guidance for an enterprise architect defining the standardized structure of
Web Services names appropriate for the enterprise. It explores the issues and best practices involved in defining and
managing enterprise naming standards. The topic is of particular importance because the structuring of the names
and the challenges involved in maintaining the consistency in naming WSDL and XML schema namespaces,
services, ports, operations, and other artifacts in the web services space have a significant impact on the complexity
of managing a SOA environment.
While the discussion and examples are focused on web services (i.e. services defined with a WSDL and SOAP), the
basic naming principles apply to other approaches such as XML over JMS and REST.
1.1 Setting Expectations

There are many possible approaches to designing names for use in SOA environments. This document sets forth one
concise set of best-practice concepts for designing names that can be readily tailored to the needs of your enterprise.
In explaining the concepts, particular emphasis is placed on explaining the rationale behind the approach so that the
refinements that will inevitably be required in practice can be designed with the same principles.
1.2 Concepts
Any discussion of service naming standards has to begin by putting a stake in the ground in terms of defining what a
service is and defining some of the related concepts. Here we run into a difference of abstraction between the
working definitions used in the broader SOA community and those provided by web services (i.e. defined by the
WSDL and SOAP schemas).
Thomas Erl provides the following statement which is generally representative of the broader SOA community
perspective:
“Each service is assigned its own distinct functional context and is comprised of a set of capabilities related
to this context. Those capabilities suitable for invocation by external consumer programs are commonly
expressed via a published service contract (much like a traditional API).” 1
The structure of the concepts in this statement is shown in Figure 1.
1
Thomas Erl, SOA: Principles of Service Design, Prentice Hall (2008) p. 39
5
Functional Context
0..*
Abstract Service
0..*
Capability
Figure 1: Abstract Service Concepts
The definition of a service is a bit more concrete in web services and is defined by the WSDL and SOAP schema
(Figure 2). In WSDL 1.1 a service consists of one or more ports, each of which is an instance of portType
(interface). Each interface consists of a number of operations. When a port (an instance of an interface) is created, it
associates an address with the port – a place to which messages can be sent. It also binds a soapAction to each
operation. WSDL 2.0, in addition to using different terms for some of the concepts, changes some of the multiplicity
constraints as well. It restricts each service to having only one interface instance, but allows each instance to have
its own set of soapAction bindings.
WSDL namespace
-name
-services 0..*
service
-name In WSDL 2.0 only
one port is allowed
per service
0..* -portTypes 0..*

port (Interface Instance) portType (Interface)
-name 0..* 1 -name
0..*
0..*
in WSDL 2.0 a port WSDL1.1 only operation
may have multiple -name
endpoints (access 1
points).
binding
WSDL 2.0 only
1 0..*
soapAction
address (endpoint)
-name
-location
Figure 2: Simplified WSDL/SOAP Service Concepts
6
While many of these concepts require names, two are particularly important: the address location and the
soapAction. The importance stems from the fact that the actual communications between the service consumer and
service provider only uses these two concepts when SOAP bindings are being used. The location is the place to
which messages are being sent, and the soapAction is the sole mechanism for indicating which operation to which
the message is related.
The relationships between the abstract concepts and the WSDL/SOAP-specific concepts is shown in Figure 3. It is
important to note that these relationships are not 1:1. For each functional context there may be a number of WSDL
namespaces - essentially sub-divisions of the functional context. Similarly an abstract service may comprise a
number of WSDL services, and each capability may comprise a number of operations.
Functional Context WSDL namespace

-name
-services 0..*
0..*
service
Abstract Service
-name In WSDL 2.0 only
one port is allowed
per service
0..* -portTypes 0..*

port (Interface Instance) portType (Interface)
-name 0..* 1 -name
0..*
0..*
0..* WSDL1.1 only operation
Capability -name
1
binding
WSDL 2.0 only

in WSDL 2.0 a port
may have multiple 1 0..*
endpoints (access soapAction
points). address (endpoint)
-name
-location
Figure 3: Relationships between Abstract and WSDL/SOAP-specific Concepts
One of the goals in naming the various concepts is to preserve an understanding of the correspondence between the
WSDL-specific components and their abstract counterparts. Since the abstractions represent design intent, then
representing this correspondence will clarify the design intent of each of the WSDL-specific components.
1.3 What’s in a Name?

When you use a service, that service and its operations need to be distinguishable from other services and
operations. This is accomplished by giving a unique name to each service and, within the service, to each port type
7
and operation of that service. Unique names are also required for the messages, data structures, and other artifacts
used in the definition of the service.
There are two significant challenges that you will encounter when creating names:
 Ensuring that each name is reasonably descriptive of each service and operation;
 Ensuring that the chosen name is, in fact, unique.
Naming standards establish how names are structured and organized and how (by whom) uniqueness is guaranteed,
and thus determine how both challenges are addressed.
1.4 Why are Naming Standards Important?

1.4.1 Names are Difficult to Change
Unfortunately, once established, names tend to become deeply embedded in service providers, service consumers,
and the components that mediate interactions between the two. Thus changing established names is expensive –
often prohibitively so. You are going to be stuck with the names you choose for a long time, so it is worth an
investment of time in considering the standards that govern their structure.
1.4.2 Name Structures Define Search Strategies

In SOA, the structure of a name not only identifies the item being named, but often indicates how to find the item.
When people are looking for an artifact, they often begin with only a vague notion of what they are looking for.
While indexes and keyword associations can be of use, the structure of the name can implicitly define a search
strategy for locating items. Consider, for example, the Amazon eCommerce service. Its WSDL has the URL:
http://ecs.amazonaws.com/AWSECommerceService/AWSECommerceService.wsdl
This name not only uniquely identifies the WSDL, it tells us where to find it: go to the machine designated by
ecs.amazonaws.com (at the default port 80), look in the AWSECommerceService directory, and obtain the file
AWSSEcommerceService.wsdl.
1.4.3 Name Structures Can Define Routing Strategies

Although it is not formally a part of the web-services paradigm, endpoint implementations often make use of names
in directing service requests to the service provider. The software component (and often the machine) that accepts
service requests is often different than the software component actually servicing those requests. Appropriate
naming can aid the component receiving the requests in routing them to the actual service provider.
For example, the locations of service endpoints (their address to which service requests are sent) are designated by
names. Consider the location of the tracking service for FedEx packages, given as:
https://gatewaybeta.fedex.com:443/web-services/track
and the location of the rate service (the service that calculates rates) for FedEx packages, given as:
https://gatewaybeta.fedex.com:443/web-services/rate
The actual component to which the requests are directed is designated by the first part of the name:
8
https://gatewaybeta.fedex.com:443
Requests are received on port 443 of gatewaybeta.fedex.com – and must be routed from there to the actual service
provider. The existence of the path structure below the internet domain name and port number makes possible two
different routing options for requests arriving at port 443. One is to route all requests to a common destination
(providing support for all web-services), and the other is to route track requests to one destination and rate requests
to another.
In contrast, the location for the FedEx service for actually shipping packages is given as:
https://gatewaybeta.fedex.com:443/web-services
In this case, the next tier of naming in the path is absent. This variation makes it difficult to use the path structure as
the basis for routing requests.
Using the structure of the location name is, of course, not the only way to route. Other information such as the
structure of the WSDL namespace and the port/operation structure underneath it can also be used for routing.
Regardless of which names are being used, the structure of the names and the consistency with which that structure
is used can greatly simplify the routing of service requests.
1.5 What needs a name?

In a SOA environment there are many things that require names. These include:
 WSDL-related names:
o The WSDL itself (the name attribute in the top-level <definitions> tag)
o The WSDL filename
o The targetNamespace defined by the WSDL (also in the top-level <definitions> tag). By
extension, the target namespace is the logical prefix for the name of each entity defined in the WSDL.
o The entities defined by the WSDL: services, port types (interface), ports (interface instances),
operations, and messages
o The soapAction
o The schemaLocation of each imported XSD file
o The location attribute for the address element of each service port
 Schema-related names:
o The XSD filename (if the schema is not embedded in a WSDL)
o The targetNamespace defined by the Schema (either embedded in the WSDL or a stand-alone
XSD). By extension, this namespace is the logical prefix for the name of each entity defined in the
schema.
o The entities defined by the schema: types, elements, and attributes
o The schemaLocation of each imported XSD file
Some of these items are actual artifacts such as files. Others are simply logical names for definitions (port types,
messages, elements, etc.) or groups of definitions (namespace names). All of them will have to be dealt with by the
producers and consumers of services. It is these names, and the standards for defining them, are the focus of this
document.
9
1.6 Purpose and Organization of this Document

The intent of this document is to provide guidance in the formulation of naming standards. It begins with a
discussion of the general principles for structuring names. These principles represent a rationale for structuring
names that should, as a rule, always be adhered to.
But principles are not enough: there are circumstances under which the principles alone will not provide a unique
solution. As these cases arise herein, guidelines are provided to indicate reasonable ways of addressing the situation
and guidance for selecting an appropriate approach.
Next, some complicating realities are discussed. Practical constraints imposed by the implementation technology
constrain the structures of names. Organizational issues of various types introduce complications that require
guidelines for resolution. The existence of multiple environments (development, test, production) and the need for
flexible deployment (for fault tolerance, high availability, site disaster recovery, or simply administrative
convenience) add wrinkles of their own. Versioning must also be taken into consideration.
The document concludes with some practical guidance for creating SOA naming standards.
1.7 The FedEx Example

Throughout this document most of the examples will be based on some services that FedEx provides. These
examples were chosen for several reasons:
 They are real web-services interfaces: you can go on-line to http://fedex.com/us/developer/ to get
the details of the actual implementations.
 The services and their operations are relatively intuitive and thus easy to understand.
 They are sufficiently complex to motivate many of the issues involved in defining SOA naming standards.
In particular, they involve more than one line of business: shipping and office printing.
 They contain reasonable and workable examples of structured names, yet they are not perfect. As such,
they illustrate some of the problems that arise in the evolution of structured names in the absence of a
guiding standard – problems that can be avoided by following some of the guidelines in this document.
Figure 4 presents an overview of the portions of the FedEx web services that will be used as examples in this
document.
10
package FedEx Example[ Overview ]
Shipping Line of Business
trackService
shipmentService rateService
ShipServicePortType TrackServicePortType RateServicePortType

+processShhipment() +track() +getRates()
+deleteShipment() +getTrackNotification()
+validateShipment() +sendSignatureProofOfDeliveryFax()
+createPendingShipment() +retrieveSignatureProofOfDeliveryLetter()
+cancelPendingShipment()
Printing Line of Business
officePrintOnlineService
PrintOnlinePortType
+getUploadLocation()
+printDocument()
+cancelPrint()
Figure 4: Overview of FedEx Example
2 Structured Name Design Principles

2.1 Use a General-to-Specific Structure
Structured names (think www.fedex.com or www.amazon.com ) are trees. As such, the root of the tree represents
the entire tree. Each node below that represents an entire subtree rooted at that node. The root of the internet (the
parent of com) is not explicitly named, but the next tier down in the internet naming system (referred to as top-level
domains) consists of nodes such as .com, .net, .org, and .edu. Within each of those domains there are
subdomains whose names are meaningful only in the context of the parent domain. Thus for uniqueness we refer to
amazon.com rather than just amazon (which has different meanings in .com, .net, and .org etc.).
Because of the inherent tree structure, it is important that the logic of the structure you define be organized around a
true hierarchy. The outline of such a hierarchy derives from the description of a service presented in the concepts
discussion earlier. From the discussion we have:
<functionalContext><service><capability>
11
This is a general-to-specific structure. A functional context may contain more than one service, and each service can
contain more than one capability. Conversely, services are specific to a particular functional context, and each
capability is specific to a particular service.
Ideally, the actual hierarchy is represented by a uniform sequence of fields in a left-to-right most-general-to-most-
specific fashion. This is the pattern we see in the naming of Java classes:
com.fedex.track.stub.TrackEvent
Where com.fedex represents the functional context, track represents the service, and stub.TrackEvent
represents the capability – in this case, the capability of representing the information associated with a track event.
Note that there is some hierarchical structure here both within the functional context and within the capability.
Unfortunately, many names in the SOA world are defined to be uniform resource identifiers (URIs) or uniform
resource locators (URLs). The structuring scheme for these does not strictly adhere to such a uniform principle.
Each URI or URL actually contains two name hierarchies, each with different construction rules. Consider our
earlier example:
http://ecs.amazonaws.com/AWSECommerceService/AWSECommerceService.wsdl
There are three parts to this string involving two different name structures:
1. The first part, http:// represents a protocol to be used to access the artifact. From a name structure
perspective, we can ignore this.
2. The second part (ecs.amazon.com) is an internet domain name that designates a machine on the internet.
In the internet domain name hierarchy is read right-to-left.
3. The third part (/AWSECommerceService/AWSECommerceService.wsdl) is called the path. It represents
a name hierarchy local to the machine designated by the internet domain name. The path name hierarchy is
read left-to-right.
What makes the use of two different name hierarchies and their differences in right-to-left and left-to-right reading
unambiguous is the use of two different separators. The internet domain namespace elements are separated by a
period (“.”), while the local namespace elements are separated by a forward slash (“/”). The occurrence of the first
slash to the right of the internet domain name is the clue that you have switched naming hierarchies.
If you wanted to make this namespace uniform, reading entirely left-to-right, you would have to switch the order of
the internet namespace elements:
com.amazon.ecs.AWSECommerceService.AWSECommerceService.wsdl
This is, of course, the kind of structure used for naming Java classes.
Best Practice: When the structure of names is not already constrained, establish a uniform left-to-right general-
to-specific hierarchical structure for names following the <functionalContext><service><capability>
pattern. When the structure of names is partially constrained (e.g. URLs and URIs), apply this principle to the
lower-level structure of the names (i.e. the path in the URL or URI).
12
2.2 Employ Hierarchical Naming Authorities

Names, to be useful, must be unique. Uniqueness requires that some authority keep track of which names have been
assigned so that newly issued names can be assured to be different. Unfortunately, having a single authority to keep
track of all names is impractical, particularly for names with global scope.
The systems that have evolved (in numerous places) to address this issue involve the use of hierarchical authorities.
This strategy involves two elements. The first is a standardized syntactic structure for defining names as sequences
of fields. The internet domain name structure (e.g. www.amazon.com) is one example.
The other is a policy that establishes authorities for maintaining the uniqueness of individual fields at different levels
of the hierarchy. For example, in the internet domain name structure, the authority for the top-level domain names
(.com, .net, .org. etc.) is ICANN (the Internet Corporation for Assigned Names and Numbers). For each of the
assigned top-level domain names, ICANN also identifies an authority for maintaining the uniqueness of the next-
level names. For the generic top-level domains (.com, .net, .org, etc.) ICANN itself is the naming authority. For
sponsored top-level domains (.edu, .gov, .mil) this authority has been delegated to other entities – one for each
sponsored domain. For example, the .edu domain is administered by EDUCAUSE, the .gov domain by the
General Services Administration of the US Government, and the .mil domain by the DoD Network Information
Center.
Each naming authority does two things:
 It directly manages the field level for which it is responsible

 It establishes the policy for managing the lower-level fields
It is in this latter point that the hierarchical authority gains its flexibility: a naming authority can delegate the
responsibility for managing subordinate namespaces. ICANN not only established fedex.com as a DNS name, it
delegated the authority for managing the lower levels of the hierarchy to FedEx Services (an organization within
FedEx). FedEx Services itself directly manages the next level of names (such as www.fedex.com and
gateway.fedex.com) and (if desired) delegates the responsibility of managing the next level of namespace (e.g.
web-services.gateway.fedex.com2).
This idea can, and should, be extended within the enterprise. Rather than having a centralized authority for
managing all names, the central authority establishes a policy for constructing names, directly manages the top
field(s) of this namespace, and delegates the authority for managing the lower-level fields.
Best Practice: Do not fully centralize the management of names in the enterprise. Instead, set up a central
authority to a) establish a generic structure for names, b) assign the values for the top-level branches of the
namespace, and c) designate appropriate authorities to manage the lower-level structure of individual branches.
2.3 Base Naming on Stable Concepts

Because of the difficulty in changing both the structure of names and the individual names that have been chosen, it
is prudent to:
2
This domain name does not actually exist – it is being used only as an example.
13
Best Practice: base the namespace structure and individual names on concepts that remain stable over time, with
the exception of enterprise identifiers.
2.3.1 Domain Concepts

The concepts that are most likely to remain stable over time are those that generically occur in any discussion of the
business. In a discussion of the shipping industry, you would tend to use general terms like package, shipment, track,
rate, shipper, recipient, and location. In banking, you would use terms general terms like customer, account, deposit,
withdrawal, payment, and transaction.
What you want to avoid are terms that are likely to change over time – particularly those with branded terminology.
Thus you would want to use the generic term “package” instead of “expressPackage”, or “account” instead of
“premierAccount”. In doing so, you hedge your bets against mergers, acquisitions, and changes in marketing.
2.3.2 Business Processes

The same rule applies when referring to naming operations associated with business processes. You want to stick
with generic names that will remain stable over time. Thus the operation for tracking a package is called simply
“track”, while the marketing-branded process may be called FedEx Track. An idealized (and somewhat simplified)
operation name for tracking a FedEx package might be something like:
com.fedex.shipments.trackingService.trackingInterface.track
2.3.3 The Exception to the Rule: Enterprise Identifiers

Names, in the context we are using, must be unique. In order to guarantee the global uniqueness of names issued by
your enterprise, you need to qualify the name with something that identifies the enterprise issuing the name. The
most common approach is to base this on the internet domain name that has been assigned to your enterprise.
This, of course, violates the notion of naming being based on stable concepts – mergers and acquisitions are
constantly changing this landscape. However, the use of the enterprise name is necessary as a hedge against mergers
and acquisitions. Without introducing the enterprise-specific prefix, the IT consolidation after a merger or
acquisition is liable to create name conflicts. Thus in the examples we have been using so far, ideally structured
names in FedEx would be prefixed by com.fedex and ideally structured names in Amazon.com would be prefixed
by com.amazon (note that the order of the fields in this idealized name structure is reversed from the internet
domain names).
2.4 Avoid Acronyms and Abbreviations

It is good practice to make the names in individual fields of the naming structure as readable and obvious as
possible.
Best Practice: Avoid using acronyms and abbreviations unless they are universally understood across an
industry.
Some common functional abbreviations that might be considered acceptable include:
HR – Human Resources
14
MKTG – Marketing
MFG – Manufacturing
FIN - Finance
2.5 Distinguish Types from Instances

It is not unusual in a WSDL or XSD to define a type and then use that type as to define an element. For example,
you might define a datatype to represent an account balance and then create an instance of that type (an element) as
a field in an account to show the current balance. Even if the structure of the defining language allows the same
name to be used for both the type and the field name, doing so can be very confusing to a human reader.
Best Practice: adopt a standard way of distinguishing type names from instance names.
Some examples of such conventions include:
 Use leading capitals to indicate types, leading lowercase to indicate instances. Thus the type for the account
balance would have the name AccountBalance, and the instance field in the account (the element
name) would have the name accountBalance.
 Append a distinguishing term to the end of the type name. Thus the type for the account balance would
have the name AccountBalanceType and the instance field in the account would have the name
accountBalance.
It is not unusual to combine the two strategies, as was done in the second example. Note that it is likely that you
already have similar standards in place for writing code. If so, you should examine those standards to determine if
they are applicable here as well. If so, you should probably adopt the existing standard rather than inventing a new
one – this will avoid confusion when people are developing code that references WSDL and XSD definitions.
2.6 Plan for Multi-Word Fields

It is often useful to be able to use more than one word when constructing a name.
Best Practice: Adopt a convention for capitalizing names that ensures that the resulting multi-word names are
readily readable.
Two common conventions that satisfy this criterion are:
 Non-Leading Capitals: each word in a field other than the first begins with a capital letter, e.g.
ShipService or shipService. The leading capital should be determined by whether the field references
a type or an instance (see previous section).
 All letters are capitalized and an underscore (“_”) or other separator is used between words, e.g.
SHIP_SERVICE. This convention pretty much requires that an additional term be used to distinguish types
from instances (see previous section).
One convention to be avoided is the use of all capitals with no special characters allowed (e.g. no underscores). Such
a convention leads to names like SHIPSERVICE, which is not only hard to read but also may lead to ambiguities.
15
2.7 Use a Distinct WSDL Namespace for Each Service

To avoid naming conflicts between the messages, ports, and operations of different services, each service should
have its own namespace.
Best Practice: Use a unique name for each service’s WSDL namespace.
Using distinct namespace makes it possible to version services independently. This will facilitate the evolution of
services in the environment. The rationale behind this best practice is explained in a companion whitepaper, “Web
Services Versioning”, available through http://www.TIBCOmmunity.com.
3 Applying the Principles:

3.1 Idealized Name Structures
Given the structured name design principles laid out above, an idealized form of structure for naming service
operations has the following structure:
<functionalContext><serviceName><portTypeName><operationName>3
Here the service capabilities (i.e. its operations) are organized hierarchically by port type. Note that WSDL 2.0 only
allows one portType per service. In this case the structure can be simplified to:
<functionalContext><serviceName><operationName>
For the datatypes involved in defining the service, you might use one or more of the following structures depending
upon the intended scope of utilization for the datatype:
<functionalContext><serviceName><portTypeName><operationName><datatypeName>
<functionalContext><serviceName><portTypeName><datatypeName>
<functionalContext><serviceName><datatypeName>
<functionalContext><datatypeName>
Similar idealized structures would apply for the messages, elements, and other artifacts involved in defining the
service.
Such idealized structures are rarely are seen in their entirety as single strings, with the possible exception of fully
qualified Java class names. In most SOA applications, the name structure is fragmented in two different ways:
 Portions of the complete name structure appear as the namespace of the WSDL or XSD, while the
remainder of the structure appears as the name of the artifact being defined in the namespace.
 Within the namespace name of the WSDL or XSD, part of the name appears as an internet domain name
while the rest appears as the path.
The following sections explore the practical use of these idealized name structures and show how they can be used
to guide and standardize the definitions of names. These will illustrate using the FedEx example. Each topic area
will first present an idealized name structure and then discuss its practical manifestation.
3
In a WSDL the scope of an operation name is the portType (WSDL 1.1) or interface (WSDL 2.0)
16
3.2 The Functional Context

In many businesses, the functional context corresponds to a line of business (or some functional subset of that line of
business). Assuming for the sake of discussion that the line of business appropriately defines the functional context,
this gives us an idealized functional context representation as:
<enterpriseID><lineOfBusiness>
In practice, the enterpriseID is almost always defined using an internet domain name. For example:
fedex.com
Most often the enterprise ID occurs in the context of a URL or URI and has the form:
http://fedex.com
FedEx, for example, has two very different lines of business - one does shipping, and the other does document
printing. The idealized functional contexts for FedEx lines of business are:
com.fedex.shipping
com.fedex.printing
In transforming the idealized form into the form needed for a URL or URI, you have two choices, differing in
whether or not you want the line of business name to be part of the internet domain name or the path. If you want it
to be part of the internet domain name, you end up with:
http://shipping.fedex.com
http://printing.fedex.com
If you want the line of business to be part of the path, you end up with:
http://fedex.com/shipping
http://fedex.com/printing
This, in practice, may not be an arbitrary choice: making the line of business part of the internet domain name
allows distinct machines to be used as targets for the different lines of business; making the line of business part of
the path forces a single machine to be used as the entry point for both lines of business. There may be organizational
and management issues involved. These are discussed in the Complicating Realities chapter.
Because of this type of situation, many enterprises have network appliances that can make seamless conversions
between these two formats. While this adds flexibility, it requires network configuration – yet another administrative
task.
3.2.1 A Notational Convention: Denoting Internet Domain Names

This question of how much of the idealized name will become part of the internet domain name occurs so often that
we will adopt a convention for indicating the answer: the portion of the idealized structure that will become the
internet domain name will be outlined. Using this convention, the example of the line-of-business name being part
of the internet domain name would be idealized as:
17
The example of the line-of-business name being part of the path would be idealized as:
In practice, the actual structure used by FedEx does not conform to either of these conventions. FedEx does not
distinguish at all between lines of business. For the URLs used to access web services, it uses a single internet
domain name and path head for all services (regardless of line of business) with the form:
https://gateway.fedex.com/web-services4
The apparent intent of using the /web-services at the head of the path is to distinguish web-services URLs from
other URLs.
3.3 Address Location Names

Address location names indicate the actual connection point (physical destination) to which operation requests are
directed. Ideally the name identifies the line of business and service, and may also indicate the port (interface). The
resulting WSDL 1.1 structures are:
<enterpriseID><lineOfBusiness><serviceName>
<enterpriseID><lineOfBusiness><serviceName><portName>
The choice between these two is, once again, not arbitrary. If the first form is used, all requests for a given service,
regardless of port, will be sent to the same location. The second form offers at least the possibility that requests for
one port may be directed to a different location than another. This difference may have real performance
implications for the subsequent design, particularly if one port provides real-time operations involving small data
structures and quick response while the other port provides batch operations involving huge data structures and
asynchronous responses. In addition, for many implementation technologies the use of this logical structure allows
the convenient routing of requests for different services and (if present) ports.
This distinction becomes moot in WSDL 2.0, since each service is only allowed to have one port. However, WSDL
2.0 allows multiple endpoints. The resulting WSDL 2.0 structures are:
<enterpriseID><lineOfBusiness><serviceName><endpointName>
For JMS bindings, the idealized structure translates in a very straightforward way into a JMS destination name:
enterpriseID.lineOfBusiness.serviceName>5
With HTTP bindings a further implementation consideration, relevant to locations is the choice of a socket number.
The structure of a URL is determined by the transport that has been selected. For http (and https) transports, the
syntax is:
http://<hostIdentifier>:<socketNumber>/<path>
4
The actual value is https://gatewaybeta.fedex.com:443/web-services
5
A fully qualified destination name provides maximum flexibility in assigning destinations to JMS servers.
18
This raises the question as to which parts of the idealized namespace should map to the <hostIdentifier> and
which parts should map to the <path>. Answering this question requires the recognition that the combination
<hostIdentifier>:<portNumber> denotes a physical destination, while the <path> is used logically at the
destination to further distinguish between requests. There are architectural tradeoffs involved in this decision, with
considerations that go beyond the scope of this document (e.g. how many sockets should there be vs. what load can
each socket reasonably handle).
For the purposes of the discussion here, consider the socketNumber to be part of the internet domain name. This
gives us the following possibilities for the idealized structure of the location URL:
The first indicates that a single socket will handle all of the service requests for the entire enterprise. This requires
centralized management of the port and a common technology touch point for all services. Generally the technology
employed here uses the <path> to redirect different requests to different sockets. The second results in a single
socket for each line of business, which again may employ technology to redirect requests to different sockets. The
third and fourth choices generally reflect the actual structure of the implementations to which requests of the first or
second type are redirected.
The actual location for the port (interface) is not consistently defined in the real FedEx WSDLs, and it deviates
somewhat from the idealized scheme. It does not utilize the line-of-business concept at all (as was discussed
previously), nor does it make any distinction between the service and the port6. In some cases, there is no indication
of the service or port at all. For example, the location for the ShipServicePort is simply:
https://gateway.fedex.com:443/web-services
This approach to addressing does not distinguish the ShipServicePort from any of the other ports. On the other
hand, the RateServicePort, TrackServicePort, and OfficePrintOnlineServicePort are distinguished
from one another in their locations by the use of a service name (even though different strings are used for the
service name):
https://gateway.fedex.com:443/web-services/rate
https://gateway.fedex.com:443/web-services/track
https://gateway.fedex.com:443/web-services/office
Since the convention followed here does not identify the lines of business, there is the potential for name conflicts
between services belonging to different lines of business. This will arise when different lines of business may want
to use the same name for different services.
Consider a bank, with separate lines of business for retail banking (checking and savings accounts), mortgages, and
credit cards. Each line of business may well have an AccountService, with operations like openAccount,
closeAccount, checkBalance, etc. Without the line-of-business field, the service names for these endpoints
would have to be augmented with some information specific to the line of business in order to keep them distinct,
e.g. retailAccountService, mortgageAccountService, creditCardAccountService, etc. In addition, to
6
In the current FedEx implementation, there is exactly one port per service.
19
ensure the uniqueness of these names, some central authority would have to maintain control over all of these names
– a tall order in a large enterprise.
For management simplicity, to avoid name conflicts it is good practice to include a line-of-business field in the
location path. With this approach, each line of business is free to manage its own namespace below the line-of-
business field. Thus we would recommend (retaining FedEx’s upper level structure) address names like:
https://gateway.fedex.com:443/web-services/shipping/ShipmentService
https://gateway.fedex.com:443/web-services/shipping/RateService
https://gateway.fedex.com:443/web-services/shipping/TrackService
https://gateway.fedex.com:443/web-services/printing/OfficePrintOnlineService
Going back to the earlier discussion about functional context, we note that the line-of-business designator may not
be sufficient to detail the full functional context. Since the potential for service naming conflicts to arise between
functional contexts, we have:
Best Practice: Include the full functional context in the location path.
3.4 WSDL and XSD Namespace Names

The idealized structure for a WSDL or XSD namespace name has the form:
<functionalContext><serviceName>
Expanding the functional context and assuming that the lineOfBusiness is sufficient to identify the functional
context, we have:
This form allows each line of business to manage the namespace below the line-of-business independently.
WSDL and XSD namespace names could use the same internet domain name structure for the <enterpriseID> as
do the port locations, but they often do not. For example, in FedEx, the WSDL and XSD namespace names follow a
different convention - they use:
http://fedex.com/ws
This gives WSDL namespaces derived from the idealized structure that look like:
http://fedex.com/ws/shipping/ShipmentService
http://fedex.com/ws/shipping/RateService
http://fedex.com/ws/shipping/TrackService
http://fedex.com/ws/printing/OfficePrintOnlineService
In reality, FedEx does not use the line of business at all in their WSDL namespaces, but they do consistently use
service names (with shortened strings). The actual WSDL namespaces used at FedEx are:
http://fedex.com/ws/ship
http://fedex.com/ws/rate
http://fedex.com/ws/track
http://fedex.com/ws/officeprintonline
Note that, in the absence of a line-of-service field, a central authority is required to guarantee the uniqueness of the
service names.
20
3.5 WSDL and XSD Filenames

A good practice is to use the structure of the WSDL or XSD namespace as the basis for defining the structure of
the filename. The idea is to make the fully qualified filename a URL (or at least a URI). Making it a URL tells you
where to locate the file. With this approach, the idealized structure for the filename is:
<enterpriseID><lineOfBusiness><serviceName><filename>
In the implementation, there are a couple of options depending on how the systems hosting the files are physically
organized. One uses a single machine as the access point for all files:
Preferable is an approach that uses one machine per line of business:
This yields the following type of URL:
http://fedex.com/ws/shipping/ShipmentService/ShipmentService.wsdl
In some situations, the file will be present in a file system. In such cases, the full structure of the name should be
preserved in the folder hierarchy of the file system. For example, you might have:
file://<root path>/com/fedex/ws/shipping/ShipmentService/ShipmentService.wsdl
This, however, can lead to deep folder structures in which there is only a single folder in each of the upper-level
folders. In such cases, the upper part of the structure can be collapsed into a single folder name:
file://<root path>/com.fedex.ws.shipping/ShipmentService/ShipmentService.wsdl
3.6 WSDL Names

To make the name of the WSDL unique, it is a good practice to make the WSDL name the same as the filename
assuming that the WSDL filename is a URL or URI.
3.7 Schema Locations

The schema location, by definition, is a URI and is ideally a URL. If the above naming practice for XSD filenames
is followed, then the fully qualified filename is the schema location.
3.8 Operation Names

An idealized structure for operation names has the form:
<functionalContext><serviceName><portTypeName><operationName>
Under our simplifying assumption that the line of business defines the functional context, we have:
<enterpriseID><lineOfBusiness><serviceName><portTypeName><operationName>
The rationale behind this structure is largely driven by practicalities in managing the names. Using the
lineOfBusiness field allows each line of business to manage its own set of service names. Within the line of
21
business, an organization can be designated to manage the port and operation names for each service. This simplifies
the management of the overall namespace.
Let’s look at the idealized structures of some real examples. Within FedEx we find a number of broad functions and
operations.
com.fedex.shipping.ShipService.ShipServicePortType
com.fedex.shipping.ShipService.ShipServicePortType.processShipment
com.fedex.shipping.ShipService.ShipServicePortType.deleteShipment
com.fedex.shipping.ShipService.ShipServicePortType.validateShipment
com.fedex.shipping.ShipService.ShipServicePortType.createPendingShipment
com.fedex.shipping.ShipService.ShipServicePortType.cancelPendingShipment
com.fedex.shipping.TrackService.TrackServicePortType
com.fedex.shipping.TrackService.TrackServicePortType.track
com.fedex.shipping.TrackService.TrackServicePortType.getTrackNotification
com.fedex.shipping.TrackService.TrackServicePortType.
sentSignatureProofOfDeliveryFax
com.fedex.shipping.TrackService.TrackServicePortType.
retrieveSignatureProofOfDeliveryLetter
com.fedex.shipping.RateService.RateServicePortType
com.fedEx.shipping.RateService.RateServicePortType.getRates
Within printing, we might find other functions and operations:
com.fedex.printing.OfficePrintOnlineService.PrintOnlinePortType
com.fedex.printing.OfficePrintOnlineService.PrintOnlinePortType.
getUploadLocation
printDocument
cancelPrint
These examples are probably a bit more verbose than you would want to use in practice. For example, the fully
spelled out “Service” might be reasonably abbreviated with “Svc”.
Note that the names of the portTypes in this idealized example replicate the name of the service. If each service is
defined in its own namespace (a recommended best practice), then this is redundant. However, if two or more
services are defined in the same namespace, then each portType name must be unique across all of the services in
the namespace. Since the service names have to also be unique in the namespace, incorporating the service name
into the portType name also guarantees the uniqueness of the portType name.
In practice, this idealized structure never appears as a single string in the WSDL file. Instead, it is divided into four
distinct parts. The first part of the structure is represented by the target namespace in the WSDL (see previous
section). Note that in our best practice this namespace includes a unique identifier of the service. The second, third,
and fourth parts are the serviceName, portTypeName, and operationName, respectively. These appear as explicit
declaration in the WSDL. For example (idealized):
<definitions xmlns:ns=http://fedex.com/ws/shipping/shipmentService
targetNamespace="http://fedex.com/ws/shipping/shipmentServce">
<portType name="ShipPortType">
<operation name="processShipment" … </operation>
<operation name="deleteShipment" … </operation>
<operation name="validateShipment" … </operation>
<operation name="createPendingShipment" … </operation>
<operation name="cancelPendingShipment" … </operation>
</portType>
22
<service name="shipService">
<port name="shipServicePort" binding="ns:ShipServiceSoapBinding" >
<s1:address location=
"https://gateway.fedex.com/web-services/shipping/ShipmentService"/>
</port>
</service>
There is a nuance here worth pointing out: portTypes are not directly associated with services. Instead, a declaration
known as a binding provides details of the portType’s implementation, and then that binding is used in defining a
port (an actual interface instance) on the service. The port has its own name. For clarity, it is good practice to choose
names for ports and portTypes that clearly distinguish between the two.
The actual WSDL used by FedEx (leaving out versions) is very similar to the idealized structure:
<definitions xmlns:ns=http://fedex.com/ws/ship
targetNamespace="http://fedex.com/ws/ship">
<portType name="ShipPortType">
<operation name="processShipment" … </operation>
<operation name="deleteShipment" … </operation>
<operation name="validateShipment" … </operation>
<operation name="createPendingShipment" … </operation>
<operation name="cancelPendingShipment" … </operation>
</portType>
<service name="ShipService">
<port binding="ns:ShipServiceSoapBinding" name="ShipServicePort">
<s1:address location= "https://gateway.fedex.com/web-services"/>
</port>
</service>
3.9 SOAP Action Names

Best Practice: Each SOAP action name should reflect the fully qualified operation name as described in the
previous section.
This approach provides the maximum flexibility in defining endpoints. With this approach, all requests could be
sent to a single endpoint (location) without ambiguity: the SOAP action uniquely identifies the required operation.
3.10 WSDL Message Names

In defining WSDL messages, there are two distinct namespaces involved: the WSDL namespace and the namespace
of the schema that defines the element used in the message. The messages themselves are defined within the WSDL
namespace. This gives us the following idealized structure for the message name:
<enterpriseID><lineOfBusiness><serviceName><messageName>
Typically each message is intended to play a particular role with respect to an operation, so it is good practice to
include the operationName as part of the message name:
<message name="processShipmentRequest">
<part element="ns:processShipmentRequest"
name="processShipmentRequest"/>
</message>
23
Each message has parts, and each part has a name which is also defined in the WSDL namespace. Since the scope of
the name is local to the message definition, the actual name is not particularly important.
The element reference in the part definition refers to an XML element that is defined in a different namespace.
These two namespaces could, theoretically, have the same name, but it is a best practice to keep the WSDL
namespace and the XML schema namespace different. By keeping them different, the same name can be used for
the both the part name (defined in the WSDL namespace) and the element name (defined in the XML schema
namespace) with no potential for name conflicts. When data structures are dedicated to particular messages, it is a
common practice to use identical names for both, thus indicating the strong tie. However, this does not preclude
creating a generic element and using it in many messages.
3.11 XSD Elements Specific to an Interface and an Operation

As mentioned in the previous section, XSD elements are often created that are dedicated for use in a single
operation. The ideal structure for an operation-specific element name would be:
<enterpriseID><lineOfBusiness><serviceName><portTypeName><operationName><elementName>
This would lead to idealized names like:
com.fedex.shipping.shipService.ShipPortType.processShipment.request
com.fedex.shipping.shipService.ShipPortType.processShipment.reply
However, XSDs limit our ability to use scoped names: the schema namespace defines the scope, but within this
scope all element names must be unique. This means that we have to divide the idealized name into two parts: one
becomes the namespace of the XSD, and the other becomes the element name.
Commonly, we let the namespace denote the serviceName:
3.11.1 A Notational Convention: Denoting Namespace Names

This question of how much of the idealized name will become part of the namespace name occurs so often that we
will adopt a convention for indicating the answer: the portion of the idealized structure that will become the
namespace name name will be placed in italics and underlined. Using this convention, letting everything up to and
including the serviceName be the namespace name would be idealized as:
<enterpriseID><lineOfBusiness><serviceName><portTypeName><operationName><elementName>
This means that the element name must be a concatenation of the portTypeName, operationName, and elementName
to create a name that is guaranteed to be unique within the namespace:
<enterpriseID><lineOfBusiness><serviceName><portTypeNameOperationNameElementName>
Recognizing that a portType defines an interface and using the interface terminology, this gives us idealized names
like:
com.fedex.shipping.ShipService.interactiveInterfaceProcessShipmentRequest
com.fedex.shipping.ShipService.interactiveInterfaceProcessShipmentReply
24
com.fedex.shipping.ShipService.batchInterfaceProcessShipmentRequest
com.fedex.shipping.ShipService.batchInterfaceProcessShipmentReply
3.12 XSD Element Specific to an Operation

A constraint that can lead to simplified names is the restriction that a service will have exactly one portType
(interface). This allows the portTypeName to be omitted from the naming structure. However, this omission can
inappropriately constrain the future growth of the service. For example, the initial portType (interface) might
provide synchronous operations to support real-time interactions. Later, it becomes necessary to introduce another
portType (interface) that supports asynchronous batch operations.
This situation continues even with WSDL 2.0. Despite the fact that each service is now restricted to having only one
interface, it is possible to define multiple services in a WSDL, each with a distinct interface. Therefore you could
end up with a batch service and an interactive service in the same WSDL.
Another constraint that allows the same name simplification is a requirement that even if there are multiple port
types (interfaces) in the service, operations with identical names occurring in two different port types must utilize
the same data structures.
Both of these constraints allow us to drop portTypeName, giving the idealized structure:
<enterpriseID><lineOfBusiness><serviceName><operationNameElementName>
In our example, we then have:
com.fedex.shipping.ShipService.ProcessShipmentRequest
com.fedex.shipping.ShipService.ProcessShipmentReply
3.13 XSD Shared Elements (Common Data Model Elements)

While the elements that represent entire messages are often specialized for the operations they support, the
subordinate elements that they reference many times can be shared between messages. If these shared elements are
specific to the service, then they belong in the service’s namespace. But if they are of more general intent (i.e. they
represent common representations of concepts used by two or more services), then they belong in a namespaces of
their own.
You might, for example, want to define the standard representation for an address type shown in Figure 5.
class Address [ Address ]
<<XSDcomplexType>>
<<XSDsequence>>
Address
<<XSDelement>>-StreetLines : string [0..2]
<<XSDelement>>-City : string [0..1]
<<XSDelement>>-StateOrProvinceCode : string [0....
<<XSDelement>>-PostalCode : string [0..1]
<<XSDelement>>-UrbanizationCode : string [0..1]
<<XSDelement>>-CountryCode : string [0..1]
<<XSDelement>>-Residential : boolean [0..1]
Figure 5: Address Element
25
Note that in addition to the Address data type, there are seven elements that the data type references. If the usage of
these elements is dedicated to the Address data type, then it would make sense to define the Address data type and
the related elements in a single namespace. To keep them separated from other concepts, you want to define a
namespace for the concept and its related elements, which we shall term here a Concept Package.
The remainder of the namespace is should be determined by the intended scope of utilization – the functional
context. If the data type is intended solely for use within a given line of business, then the namespace should reflect
that. This gives us a general structure of:
<enterpriseID><lineOfBusiness><ConceptPackage><ConceptTypeName>
<enterpriseID><lineOfBusiness><ConceptPackage><elementName>
For the FedEx example, this gives us idealized structures like:
com.fedex.shipping.Address.Address
com.fedex.shipping.Address.street
com.fedex.shipping.Address.city
com.fedex.shipping.Address.state
If the intended scope of utilization crosses line-of-business, then we will have a general structure of:
<enterpriseID><ConceptPackage><ConceptTypeName>
<enterpriseID><ConceptPackage><elementName>
For the FedEx example, this gives us idealized structures like:
com.fedex.Address.Address
com.fedex.Address.street
com.fedex.Address.city
com.fedex.Address.state
4 Complicating Realities
4.1 Technology Constraints
Reality often constrains the ideal approach. This is particularly true with names. Ideally, names have no restrictions
with respect to either the number of fields or the length of any individual field. Unfortunately, this does not hold true
in practice. The various technologies being employed have both theoretical restrictions and practical limitations.
Internet domain names limit the number of fields in a name to 127, and allow each field to contain up to 63 octets
(bytes). The whole domain name (including “.” Separators) is limited to 253 octets. In practice, some domain
registries may have shorter limits.
The JMS standard places no limitations on names, but vendor implementations often do. For example, TIBCO EMS
destinations can have up to 64 fields. Individual fields cannot exceed 127 characters. Destination names are limited
to a total length of 249 characters.
Whatever naming standards are established, they must obviously take into consideration the constraints of the
chosen supporting technologies.
26
There is a practical limitation to consider as well. By default, every byte (octet) of every name must be transmitted
with every message. Thus it is a good practice to avoid excessive length in names, while at the same time preserving
the readability of the name.
4.2 Organizational Issues

4.2.1 Naming Authorities
Every position in a naming hierarchy requires an authority for its administration. As discussed earlier, each naming
authority a) directly manages the field level for which it is responsible, and b) establishes the policy for managing
the lower-level fields.
The ability to delegate the management of the lower-level structures is part of the power of hierarchical name
structures. At the enterprise level, the authority must:
 Assign names to represent each of the lines of business

 Identify who in each line of business will manage the lower-level structures below the line-of-business field
 Assign names to represent each enterprise-level service
 Identify who will manage the lower-level structure for each enterprise service
 Assign names to represent each enterprise-level concept package
 Identify who will manage the lower-level structure for each enterprise concept package
Within each line of business, the responsibilities are similar, assigning names for line-of-business services and
concept packages and identifying who will manage the lower-level structures for each. In very large organizations,
lines of business may actually define subordinate structures to further organize services and concepts. This yields
name structures like:
<enterpriseID><lineOfBusiness><servicePackage><serviceName>
<enterpriseID><lineOfBusiness><servicePackage><conceptPackage>
4.2.2 Complex Organizational Structures

4.2.2.1 Functional Organizations
If a line-of-business organization is functionally complete (i.e. horizontally integrated), then all of the services and
concepts required to operate the line of business are part of that organization. The naming structure we have been
discussing reflects this singular line of authority over all the services and concepts relevant to the organization.
Many organizations, however, are structured functionally rather than by line of business. An organization might
have functional groups for marketing, sales, logistics, finance, engineering, manufacturing, etc. If such an
organization provides capabilities uniformly across multiple lines of business, the top-level structure may be more
appropriately based on function rather than line of business:
<enterpriseID><function>
27
4.2.2.2 Mixed Functional and Line-of-Business Organizations

Often organizations combine these two approaches. A line-of-business organization may well have a functional
substructure under each line of business. In such cases, the structure of the functional context must be expanded.
This gives a functional context of:
<enterpriseID><lineOfBusiness><function>
Less frequently it may be appropriate to reverse the hierarchy:
<enterpriseID><function><lineOfBusiness>
The challenge here is that there are, in reality, two hierarchies: the functional hierarchy and the line-of-business
hierarchy. Yet the representational technology (WSDL and XSD) only allows for one hierarchy, so the two must be
combined into a single functional context. This forces one to be somewhat arbitrarily chosen to dominate over the
other.
Regardless of how the hierarchies are combined, some caution is in order: enterprises tend to reorganize. Since you
are going to be living with the namespace structure even after the reorganization, it is important to choose names for
both functions and lines of business that will remain stable over time. Bear in mind that a single organization may
actually serve more than one functional purpose (e.g. sales and marketing could be in one parent organization) or
serve more than one line-of-business purpose (e.g. a division that handles multiple lines-of-business). In such cases,
each individual purpose should have a distinct name in the namespace. This makes the namespace structure
relatively stable with respect to reorganization.
4.2.2.3 Geographic Distribution

Another challenge you are liable to encounter is geographic distribution. This is particularly true for multinational
enterprises, where the operations in different countries or regions tend to be conducted by legally distinct entities.
This adds yet a third hierarchy to the ways that the enterprise can be viewed (Figure 6).
package Hierarchies [ Multiple Hierarchies ]
Global Enterprise
-regions -functions -linesOfBusiness

Geographic Region -subRegions Function -subFunctions
LineOfBusiness -subLinesOfBusiness
Figure 6: Multiple Hierarchical Concepts for the Enterprise
The presence of yet a third hierarchy further complicates functional context. One possible structure that could
emerge is:
<enterpriseID><lineOfBusiness><function><geographicRegion>
28
This is but one of six possible combinations, and that does not even count the possibilities of leaving one or more of
the hierarchies out of the structure entirely. Altogether, there are 15 possibilities. So how do you select the one for
your enterprise?
There are two factors that should drive your thinking. The first one is driven by organizational realities. In this you
need to consider the following:
 What does the current organizational structure look like (i.e. what is the actual organizational hierarchy
today)
 What are the realistic prospects for cooperation between organizations?
o Is there a place in the parent organization for a working group to manage namespaces that cross
organizational boundaries?
o Is there sufficient authority for such a working group to effectively manage such a namespace (i.e.
will the other organizations listen)?
If the prospects look dim for cooperation between organizational units, then you have little choice other than to
adopt a namespace structure that treats the organizations as being independent.
The other factor to consider is the intended future direction for the enterprise in terms of sharing data, resources,
services, and business processes across the organization. If there is an effort underway (which presupposes that there
is a reasonable prospect for cooperation between organizations), then the hierarchy you choose should be one that
makes the most sense with respect to the chosen direction.
4.3 Environments: Values for Address Variables

Each service will, in its lifetime, exist in a number of environments, ranging from development through several test
environments and finally one or more production environments. Thus it becomes necessary to distinguish between
the different instances of the service when accessing the service.
The logical place to make this distinction would be in the port address in the WSDL. Unfortunately, the structure of
the WSDL does not make provisions for designating different addresses in different environments. Furthermore,
changing the WSDL (to indicate the different environment) requires changes to the consumer as well as the provider
(or at least the ESB). Since the WSDL is the service interface definition, edits to the WSDL could potentially change
anything. Thus editing the WSDL invalidates whatever testing has been performed and thus defeats the purpose of
the WSDL as a specification.
To work around this limitation, most service consumer and service provider implementation technologies allow the
address of the endpoint to be provided by a variable whose value is set at deployment time. With this approach,
environments must be distinguished within the values provided for the address variable. These addresses (the
provided values) need to be distinct from one another while remaining descriptive of their purpose so that they can
be accurately and appropriately set at deployment time.
Referring back to the earlier discussion of port addresses, a portion of the idealized address structure maps to the
hostIdentifier. This is the level at which development, test, and production environments should be distinguished
from one another. Using the scheme described earlier, we have the following possibilities (the portions in the box
correspond to the host identifier):
<enterpriseID><environment><lineOfBusiness><serviceName><portName>
29
<enterpriseID><lineOfBusiness><environment><serviceName><portName>
<enterpriseID><lineOfBusiness><serviceName><environment><portName>
<enterpriseID><lineOfBusiness><serviceName><portName><environment>
For HTTP bindings, manifestation of the <environment> can take one of two forms: it can be the hostIdentifier itself
or the socket on the host. If different hosts are being used then the FedEx example would have:
https://dev.gateway.fedex.com:443/web-services/shipping/ShipmentService
https://test.gateway.fedex.com:443/web-services/shipping/ShipmentService
https://prod.gateway.fedex.com:443/web-services/shipping/ShipmentService
If different ports on the same host are being used the FedEx example would have:
It is generally not a good practice to use the same port for multiple environments.
For JMS bindings, the manifestation of the <environment> can also take one of two forms: it can be the JMS server
itself or it can be included directly in the queue name. If the same JMS server is being used, the server itself
represents the enterpriseID. The resulting destination names for the FedEd example would be:
dev.shipping/ShipmentService
test.shipping/ShipmentService
prod.shipping/ShipmentService
If different servers are being used then each server represents both the enterpriseID and the environment. The
resulting destination names for the FedEx example would all have the same value:
dev.shipping/ShipmentService
4.4 Deployment Flexibility

A port location (at least in the http[s] type of addressing) identifies a specific machine to which requests are to be
sent. Should this machine move, all the services accessed through that machine would become unavailable. One way
around this is to use virtual IP addresses or hostnames, allowing the networking infrastructure to reroute requests to
another machine. Another approach is to make the location string actually an http query whose response is the real
service address. Amazon ecommerce web services, for example, use this approach:
<soap:address
location="https://ecs.amazonaws.com/onca/soap?Service=AWSECommerceService"/>
Abstracting the logical structure here, the <hostIdentifier>/<path> part of the location actually identifies the
server to which the query is being submitted, while the value of the Service parameter indicates the desired
service. This approach facilitates the flexible rehosting of the actual service providers over time.
For greatest flexibility, it is recommended that the full path name of the port be used as the argument for the query.
Thus if one query service is being used to support the entire enterprise, the value for the query would have the
structure:
<lineOfBusiness><serviceName><portName>
If the query service supports just a line of business, then the query value would be:
30
<serviceName><portName>
It is not good practice to use the same query service for different environments.
SOAP over JMS utilizes JNDI lookups in a similar manner. The same considerations apply.
4.5 Versioning
Services are bound to change over time. When incompatible (non-backwards compatible) changes are made to
services, the version of the service must somehow be indicated. It is best practice to place version numbers at the
end of WSDL and XSD namespace names, giving a structure like:
<enterpriseID><lineOfBusiness><serviceName><version>
<enterpriseID><lineOfBusiness><ConceptPackage><version>
Versioning is, however, a more complicated topic that can influence many different names in different ways. Please
refer to the whitepaper on Web Services Versioning for more details.
5 Developing Your Standard

To begin with, you need to identify the organization that will have overall responsibility for the naming standards in
your enterprise. If you are in the early stages of adopting SOA, you may not be in a position to mandate that a
particular naming structure be followed. Nevertheless, there is no reason that you cannot adopt a structure that will
appropriately generalize to the needs of the larger enterprise as outlined in this document.
The enterprise-level authority has several responsibilities. One is to define an overall strategy for:
 WSDL and XSD namespace names, including versioning

 Location names, including:
o Versioning
o Directing requests to the appropriate environment
o Using indirection (http query or JNDI lookup) for addresses
Another responsibility is to identify which organizations will be responsible for managing the lower levels of the
naming structure. If the enterprise is large, this will likely mean identifying an organization in each line of business
responsible for names used in that line of business. Each of those organizations, in turn, will have to determine how
much of the naming structure it will directly manage and how much management responsibility it will delegate to
other organizations.
31

Web Services Naming Standards A Guide For Enterprise Architects

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Web Services Naming Standards A Guide For Enterprise Architects

Transféré par

Droits d'auteur :

Formats disponibles

Web Services Naming Standards

Web Services Naming Standards

A Guide for Enterprise Architects

Copyright TIBCO Software

3.9 SOAP Action Names ..................................................................................................................................... 23

1.1 Setting Expectations

The structure of the concepts in this statement is shown in Figure 1.

Figure 1: Abstract Service Concepts

0..* -portTypes 0..*

WSDL 2.0 only

Figure 2: Simplified WSDL/SOAP Service Concepts

Functional Context WSDL namespace

0..* -portTypes 0..*

WSDL 2.0 only

Figure 3: Relationships between Abstract and WSDL/SOAP-specific Concepts

1.3 What’s in a Name?

1.4 Why are Naming Standards Important?

1.4.2 Name Structures Define Search Strategies

1.4.3 Name Structures Can Define Routing Strategies

1.5 What needs a name?

1.6 Purpose and Organization of this Document

1.7 The FedEx Example

package FedEx Example[ Overview ]

Shipping Line of Business

ShipServicePortType TrackServicePortType RateServicePortType

Printing Line of Business

Figure 4: Overview of FedEx Example

2 Structured Name Design Principles

2.2 Employ Hierarchical Naming Authorities

Each naming authority does two things:

 It directly manages the field level for which it is responsible

2.3 Base Naming on Stable Concepts

2.3.1 Domain Concepts

2.3.2 Business Processes

2.3.3 The Exception to the Rule: Enterprise Identifiers

2.4 Avoid Acronyms and Abbreviations

Some common functional abbreviations that might be considered acceptable include:

2.5 Distinguish Types from Instances

Some examples of such conventions include:

2.6 Plan for Multi-Word Fields

Two common conventions that satisfy this criterion are:

2.7 Use a Distinct WSDL Namespace for Each Service

3 Applying the Principles:

3.2 The Functional Context

3.2.1 A Notational Convention: Denoting Internet Domain Names

3.3 Address Location Names

3.4 WSDL and XSD Namespace Names

3.5 WSDL and XSD Filenames

Preferable is an approach that uses one machine per line of business:

This yields the following type of URL:

3.6 WSDL Names

3.7 Schema Locations

3.8 Operation Names

Within printing, we might find other functions and operations:

3.9 SOAP Action Names

3.10 WSDL Message Names

3.11 XSD Elements Specific to an Interface and an Operation

This would lead to idealized names like:

Commonly, we let the namespace denote the serviceName:

3.11.1 A Notational Convention: Denoting Namespace Names

3.12 XSD Element Specific to an Operation

In our example, we then have:

3.13 XSD Shared Elements (Common Data Model Elements)