UDDI Spec TC

UDDI Version 2.03 Data Structure Reference

UDDI Committee Specification, 19 July 2002

Document identifier:

DataStructure_v2

Location:

http://uddi.org/pubs/DataStructure-V2.03-Published-20020719.htm

Latest version:

http://uddi.org/pubs/DataStructure_v2.htm

Editors:

Claus von Riegen, SAP

Contributors:

Tom Bellwood, IBM

David Ehnebuske, IBM
Yin Leng Husband, HP

Alan Karp, HP

Keisuke Kibakura, Fujitsu

Jeff Lancelle, Verisign

Sam Lee, Oracle

Sean MacRoibeaird, Sun

Barbara McKee, IBM

Tammy Nordan, HP

Dan Rogers, Microsoft

Christine Tomlinson, Sun

Cafer Tosun, SAP

Acknowledgements:

The UDDI Spec TC recognizes the contributions of other participants from the UDDI.org Working Group:

Andy Harris, i2 Technologies

Denise Ho, Ariba

UDDI Business Registry Operators Council

Abstract:

The UDDI Version 2.0 API Specification defines approximately 40 SOAP messages that are used to perform inquiry and publishing functions against any UDDI compliant service registry. This document outlines the details of each of the XML structures associated with these messages.

Status:

This specification has attained the status of OASIS Standard.

Committee members should send comments on this Committee Specification to the uddi-spec@lists.oasis-open.org list. Others should subscribe to and send comments to the uddi-spec-comment@lists.oasis-open.org list. To subscribe, send an email message to uddi-spec-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.

For information on whether any intellectual property claims have been disclosed that may be essential to implementing this Committee Specification, and any offers of licensing terms, please refer to the Intellectual Property Rights section of the UDDI Spec TC web page (http://www.oasis-open.org/committees/uddi-spec/).

Copyrights

Copyright © 2001-2002 by Accenture, Ariba, Inc., Commerce One, Inc., Fujitsu Limited, Hewlett-Packard Company, i2 Technologies, Inc., Intel Corporation, International Business Machines Corporation, Microsoft Corporation, Oracle Corporation, SAP AG, Sun Microsystems, Inc., and VeriSign, Inc. All Rights Reserved.

Contents

1 Terminology. 5

2 Introduction. 5

2.1 Service Discovery. 5

2.1.1 Five data types. 5

3 Overall Design Principles. 6

3.1 Unique identifiers. 6

3.2 Containment 7

4 Data Structure Notation. 7

5 The businessEntity structure. 8

5.1 Structure specification. 8

5.2 Substructure breakdown. 8

5.2.1 discoveryURLs. 9

5.2.2 name. 10

5.2.3 contacts. 10

5.2.4 businessServices. 12

5.2.5 identifierBag. 12

5.2.6 categoryBag. 13

6 The businessService structure. 13

6.1 Structure Specification. 13

6.2 Substructure Breakdown. 14

6.2.1 bindingTemplates. 15

7 The bindingTemplate structure. 15

7.1 Structure specification. 15

7.2 Substructure breakdown. 15

7.2.1 accessPoint 16

7.2.2 hostingRedirector 17

7.2.3 tModelInstanceDetails. 17

8 The tModel structure. 19

8.1 Two main uses. 19

8.1.1 Defining the technical fingerprint 19

8.1.2 Defining an abstract namespace reference. 20

8.2 Structure specification. 20

8.3 Substructure breakdown. 21

9 The publisherAssertion structure. 22

9.1 Structure Specification. 22

9.2 Substructure Breakdown. 22

Appendix A: Using Identifiers. 23

A.1 The identifier dilemma. 23

A.2 Identifier characteristics. 23

A.2.1 Using identifiers. 24

A.2.2 Structure Specification. 25

Appendix B: Using categorization. 26

B.1 Structure Specification. 27

Appendix C: Response message reference. 28

C.1 assertionStatusReport 28

C.4 businessDetail 29

C.4.1 Sample. 29

C.5 businessDetailExt 30

C.5.1 Sample. 30

C.6 businessList 30

C.6.1 Sample. 30

C.7 publisherAssertions. 31

C.7.1 Sample. 31

C.8 registeredInfo. 31

C.8.1 Sample. 31

C.9 relatedBusinessesList 32

C.9.1 Sample. 32

C.10 serviceDetail 32

Appendix D: Data Field Lengths. 34

Appendix E: Structured Address Example. 35

Appendix F: Notices. 36

1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

2 Introduction

The programmatic interface provided for interacting with systems that follow the Universal Description Discovery & Integration (UDDI) specifications make use of Extensible Markup Language (XML) and a related technology called Simple Object Access Protocol (SOAP), which is a specification for using XML in simple message based exchanges.

2.1 Service Discovery

The purpose of UDDI compliant registries is to provide a service discovery platform on the World Wide Web. Service discovery is related to being able to advertise and locate information about different technical interfaces exposed by different parties. Services are interesting when you can discover them, determine their purpose, and then have software that is equipped for using a particular type of Web service complete a connection and derive benefit from a service.

A UDDI compliant registry provides an information framework for describing services exposed by any entity or business. In order to promote cross platform service description that is suitable to a “black-box[1]” Web environment, this description is rendered in cross-platform XML.

2.1.1 Five data types

The information that makes up a registration consists of five data structure types. This division by information type provides simple partitions to assist in the rapid location and understanding of the different information that makes up a registration.

The five core types are shown in figure 1.

These five types make up the complete amount of information provided within the UDDI service description framework. Each of these XML structures contains a number of data fields[2] that serve either a business or technical descriptive purpose. Explaining each of these structures and the meaning and placement of each field is the primary purpose of this document.

These structures are defined in the UDDI Version 2.0 API schema. The schema defines approximately 25 requests and 15 responses, each of which contain these structures, references to these structures, or summary versions of these structures. In this document we first explain the core structures, and then provide descriptions of the individual structures used for the request/response XML SOAP interface.

Figure 1

3 Overall Design Principles

Each of the five structure types is used to express specific types of data, arranged in the relationship shown in Figure 1. A particular instance of an individual fact or set of related facts is expressed using XML according to the definition of these core types. For instance, two separate businesses may publish information about the Web services they offer, whether these services are entry points for interfacing with accounting systems, or even services that allow customers to query the status of a factory order. Each business, and the corresponding service descriptions (both logical and technical descriptions) all exist as separate instances of data within a UDDI registry.

3.1 Unique identifiers

The individual facts about a business, its services, technical information, or even information about specifications for services are kept separate, and are accessed individually by way of unique identifiers, or keys. A UDDI registry assigns these unique identifiers when information is first saved, and these identifiers can be used later as keys to access the specific data instances on demand.

Each unique identifier generated by a UDDI registry takes the form of a Universally Unique ID[3] (UUID). Technically, a UUID is a hexadecimal string that has been generated according to a very exacting algorithm that is sufficiently precise as to prevent any two UUIDs from ever being generated in duplicate[4].

3.2 Containment

The individual instance data managed by a UDDI registry are sensitive to the parent/child relationships found in the XML schema. This same containment relationship is seen in figure 1 for the core structures. The businessEntity structure contains one or more unique businessService structures. Similarly, individual businessService structures contain specific instances of bindingTemplate data, which in turn contains information that includes pointers to specific instances of tModel structures.

It is important to note that no single instance of a core structure type is ever “contained” by more than one parent structure. This means that only one specific businessEntity structure (identified by its unique key value) will ever contain or be used to express information about a specific instance of a businessService structure (also identified by its own unique key value).

References, on the other hand, operate differently. We can see an example of this in figure 1 where the bindingTemplate structures contain references to unique instances of tModel structures. References can be repeated within any number of the core typed data instances such that many references to a single unique instance are allowed.

Determining what is a reference to an instance of a core data type and what is a key for a core data type within a specific instance is straightforward. There are five core data types, and instances of each of these types are identified by unique keys. The businessKey found within the businessEntity structure is a key, and not a reference. Similarly, the serviceKey and bindingKey values found respectively within the businessService and bindingTemplate structures are keys. The same holds true for the tModelKey value found within the tModel structure. The publisherAssertion’s key is logically the concatenation of all of its elements.

References on the other hand, occur in several places, especially for tModels. When tModels are referenced, as seen within a bindingTemplate structure, these occur within a list structure designed for the purpose of holding references to tModels. This list, not being one of the five core data types, is not keyed as an individual instance. Rather, its own identity is derived from the parent structure that contains it – and it cannot be separated. Thus any key values directly contained in structures that are not themselves one of the five core structure types are references. Examples include tModelKey values found in lists within bindingTemplate and categorization and identification schemes – in which context the tModel represents a uniquely identifiable namespace reference and qualifier.

4 Data Structure Notation

Data structures are described by substructure breakdowns in tables of the following form.

Field Name

Description

Data Type

Length

Optional fields are written in normal font

Description of the field’s meaning and whether it’s

An attribute or an element
Repeatable or not

Possible Data Types include

structure
string
UUID

If the field’s data type is string, the field’s length is given here in Unicode characters

Required fields are written in bold font

Most of the data structures are also given in their XML Schema representation. Please use the UDDI XML Schema as the definitive technical reference, if needed.

5 The businessEntity structure

The businessEntity structure represents all known information about a business or entity that publishes descriptive information about the entity as well as the services that it offers. From an XML standpoint, the businessEntity is the top-level data structure that accommodates holding descriptive information about a business or entity. Service descriptions and technical information are expressed within a businessEntity by a containment relationship.

5.1 Structure specification

</sequence>

</complexType>

5.2 Substructure breakdown

Field Name	Description	Data Type	Length
businessKey	Attribute. This is the unique identifier for a given instance of a businessEntity structure.	UUID	41
authorizedName	Attribute. This is the recorded name of the individual that published the businessEntity data. This data is generated by the controlling operator and should not be supplied within save_business operations.	string	255
operator	Attribute. This is the certified name of the UDDI registry site operator that manages the master copy of the businessEntity data. The controlling operator records this data at the time data is saved. This data is generated and should not be supplied within save_business operations.	string	255
discoveryURLs	Optional element. This is a list of Uniform Resource Locators (URL) that point to alternate, file based service discovery mechanisms. Each recorded businessEntity structure is automatically assigned a URL that returns the individual businessEntity structure. URL search is provided via find_business call.	structure
name	Required repeating element. These are the human readable names recorded for the businessEntity, adorned with a unique xml:lang value to signify the language that they are expressed in. Name search is provided via find_business call. Names may not be blank.	string	255
description	Optional repeating element. One or more short business descriptions. One description is allowed per national language code supplied.	string	255
contacts	Optional element. This is an optional list of contact information.	structure
businessServices	Optional element. This is a list of one or more logical business service descriptions.	structure
identifierBag	Optional element. This is an optional list of name-value pairs that can be used to record identifiers for a businessEntity. These can be used during search via find_business.	structure
categoryBag	Optional element. This is an optional list of name-value pairs that are used to tag a businessEntity with specific taxonomy information (e.g. industry, product or geographic codes). These can be used during search via find_business.	structure

5.2.1 discoveryURLs

The discoveryURLs structure is used to hold pointers to URL addressable discovery documents. The expected retrieval mechanism for URLs referenced in the data within this structure is HTTP-GET. The expected return document is not defined. Rather, a framework for establishing convention is provided, and two such conventions are defined within UDDI behaviors. It is hoped that other conventions come about and use this structure to accommodate alternate means of discovery.[5]

Field Name	Description	Data Type	Length
discoveryURL	Attribute qualified repeating element holding strings that represent web addressable (via HTTP-GET) discovery documents.	string w/attributes	255

5.2.1.1 discoveryURL

Each individual discovery URL consists of an attribute whose value designates the URL use type convention, and a string, found within the body of the element. Each time a businessEntity structure is saved via a call to save_business, the UDDI Operator Site will generate one URL. The generated URL will point to an instance of either a businessEntity or businessEntityExt structure, and the useType attribute of the discoveryURL will be set to either "businessEntity" or "businessEntityExt" according to the data type found while processing the save_business message. The discoveryURLs collection will be augmented so that it includes this generated URL. This URL can then be used to retrieve a specific instance of a businessEntity, since the XML returned will be formatted as a normal businessDetail message.

Field Name	Description	Data Type	Length
useType	Required attribute that designates the name of the convention that the referenced document follows. Two reserved convention values are “businessEntity” and “businessEntityExt”. URLs qualified with these values should point to XML documents of the same type as the useType value.	string	255

Example: An example of the generated data for a given businessEntity might look similar to the following:

http://www.someOperator?businessKey=BE3D2F08-CEB3-11D3-849F-0050DA1803C0

</discoveryURL>

5.2.2 name

A businessEntity MAY contain more than one name. Multiple names are useful, for example, in order to specify both the legal name and a known abbreviation of a businessEntity, or in order to support romanization.

When a name is expressed in a specific language (such as the language into which a name has been romanized), it SHOULD carry the xml:lang attribute to signify this. When a name does not have an associated language (such as a neologism not associated with a particular language), the xml:lang attribute SHOULD be omitted.

As is defined in the XML specification, an occurrence of the xml:lang attribute indicates that the content to which it applies (namely the element on which it is found and to all its children, unless subsequently overridden) is to be interpreted as being in a certain natural language. Legal values for such attributes are specified in the IETF standard RFC 1766 and its successors (including, as of the time of the present writing, RFC 3066). As is indicated therein, language values begin with a primary language tag, and are optionally followed by a series of hyphen-delimited sub-tags for country or dialect identification; the tags are not case-sensitive. Examples include: "EN-us", "FR-ca".

The same mechanism applies to the name element within the businessService structure.

5.2.3 contacts

The contacts structure provides a way for information to be registered with a businessEntity record so that someone that finds the information can make human contact for any purpose. Since the information held within the UDDI Operator Sites is freely available, some care should be taken when considering the amount of contact information to register. Electronic mail addresses in particular may be the greatest concern if you are sensitive to receiving unsolicited mail.

The contacts structure itself is a simple collection of contact structures. You’ll find that there are many collections in the UDDI Version 2.0 API schema. Like the discoveryURLs structure – which is a container for one or more discoveryURL structures, the contacts structure is a simple container where one or more contact structures reside.

5.2.3.1 contact

The contact structure lets you record contact information for a person. This information can consist of one or more optional elements, along with a person’s name. Contact information exists by containment relationship alone, and no mechanisms for tracking individual contact instances is provided by UDDI specifications.

For transliteration purposes (e.g. romanization) the suggested approach is to file multiple contacts.

Field Name	Description	Data Type	Length
useType	Optional attribute that is used to describe the type of contact in freeform text. Suggested examples include “technical questions”, “technical contact”, “establish account”, “sales contact”, etc.	string	255
description	Optional element. Zero or more language-qualified^{^[6]} descriptions of the reason the contact should be used.	string	255
personName	Required element. Contacts should list the name of the person or name of the job role that will be available behind the contact. Examples of roles include “administrator” or “webmaster”.	string	255
phone	Optional repeating element. Used to hold telephone numbers for the contact. This element can be adorned with an optional useType attribute for descriptive purposes.	string w/attributes	50
email	Optional repeating element. Used to hold email addresses for the contact. This element can be adorned with an optional useType attribute for descriptive purposes.	string w/attributes	255
address	Optional repeating element. This structure represents the printable lines suitable for addressing an envelope.	structure

5.2.3.2 address

The address structure is a simple list of addressLine elements within the address container. Each addressLine element is a simple string. UDDI compliant registries are responsible for preserving the order of any addressLine data provided. Address structures also have three optional attributes. The useType describes the address’ type in freeform text. The sortCode values are not significant within a UDDI registry, but may be used by user interfaces that present contact information in some ordered fashion using the values provided in the sortCode attribute. The tModelKey is a tModel reference that specifies that keyName keyValue pairs given by subsequent addressLine elements, if addressLine elements are present at all, are to be interpreted by the address structure associated with the tModel that is referenced. For a description of how to use tModels in order to give the simple addressLine list structure and meaning, see Appendix E: Structured Address Example.

Field Name	Description	Data Type	Length
useType	Optional attribute that is used to describe the type of address in freeform text. Suggested examples include “headquarters”, “sales office”, “billing department”, etc.	string	255
sortCode	Optional attribute that can be used to drive the behavior of external display mechanisms that sort addresses. The suggested values for sortCode include numeric ordering values (e.g. 1, 2, 3), alphabetic character ordering values (e.g. a, b, c) or the first n positions of relevant data within the address.	string	10
tModelKey	Optional attribute. This is the unique key reference that implies that the keyName keyValue pairs given by subsequent addressLine elements are to be interpreted by the taxonomy associated with the tModel that is referenced.	string	255 41^{^[7]}
addressLine	Optional repeating element containing the actual address in freeform text. If the address element contains a tModelKey, these addressLine elements are to be adorned each with an optional keyName keyValue attribute pair. Together with the tModelKey, keyName and keyValue qualify the addressLine in order to describe its meaning.	string w/attributes	80

5.2.3.3 addressLine

AddressLine elements contain string data with a line length limit of 80 character positions. Each addressLine element can be adorned with two optional descriptive attributes, keyName and keyValue. Both attributes must be present in each address line if a tModelKey is assigned to the address structure. By doing this, the otherwise arbitrary use of address lines becomes structured. Together with the address’ tModelKey, the keyName and keyValue qualify the addressLine according to the address structure specified in the overview document of the referenced tModel. See Appendix E for an example how structured addresses can be represented. When no tModelKey is provided for the address structure, the keyName and keyValue attributes can be used without restrictions, for example, to provide descriptive information for each addressLine by using the keyName attribute. Since both the keyName and the keyValue attributes are optional, address line order is significant and will always be returned by the UDDI compliant registry in the order originally provided during a call to save_business.

5.2.4 businessServices

The businessServices structure provides a way for describing information about families of services. This simple collection accessor contains zero or more businessService structures and has no other associated structures.

5.2.5 identifierBag

The identifierBag element allows businessEntity or tModel structures to include information about common forms of identification such as D-U-N-S^â numbers, tax identifiers, etc. This data can be used to signify the identity of the businessEntity, or can be used to signify the identity of the publishing party. Including data of this sort is optional, but when used greatly enhances the search behaviors exposed via the find_xx messages defined in the UDDI Version 2.0 API Specification. For a full description of the structures involved in establishing an identity, see Appendix A: Using Identifiers.

5.2.6 categoryBag

The categoryBag element allows businessEntity, businessService and tModel structures to be categorized according to any of several available taxonomy based classification schemes. Operator Sites automatically provide validated categorization support for three taxonomies that cover industry codes (via NAICS), product and service classifications (via UNSPC) and geography (via ISO 3166). Including data of this sort is optional, but when used greatly enhances the search behaviors exposed by the find_xx messages defined in the UDDI Version 2.0 API Specification. For a full description of structures involved in establishing categorization information, see Appendix B: Using categorization.

6 The businessService structure

The businessService structures each represent a logical service classification. The name of the element includes the term “business” in an attempt to describe the purpose of this level in the service description hierarchy. Each businessService structure is the logical child of a single businessEntity structure. The identity of the containing (parent) businessEntity is determined by examining the embedded businessKey value. If no businessKey value is present, the businessKey must be obtainable by searching for a businessKey value in any parent structure containing the businessService. Each businessService element contains descriptive information in business terms outlining the type of technical services found within each businessService element.

In some cases, businesses would like to share or reuse services, e.g. when a large enterprise publishes separate businessEntity structures. This can be established by using the businessService structure as a projection to an already published businessService.

Any businessService projected in this way is not managed as a part of the referencing businessEntity, but centrally as a part of the referenced businessEntity. This means that changes of the businessService by the referenced businessEntity are automatically valid for the service projections done by referencing businessEntity structures.

In order to specify both referenced and referencing businessEntity structures correctly, service projections can only be published by a save_business message with the referencing businessKey present in the businessEntity structure and both the referenced businessKey and the referenced businessService present in the businessService structure.

6.1 Structure Specification

</sequence>

</complexType>

6.2 Substructure Breakdown

Field Name

Description

Data Type

Length

businessKey

This attribute is optional when the businessService data is contained within a fully expressed parent that already contains a businessKey value.

If the businessService data is rendered into XML and has no containing parent that has within its data a businessKey, the value of the businessKey that is the parent of the businessService is required to be provided. This behavior supports the ability to browse through the parent-child relationships given any of the core elements as a starting point. The businessKey may differ from the publishing businessEntity’s businessKey to allow service projections.

UUID

serviceKey

This is the unique key for a given businessService. When saving a new businessService structure, pass an empty serviceKey value. This signifies that a UUID value is to be generated. To update an existing businessService structure, pass the UUID value that corresponds to the existing service. If this data is received via an inquiry operation, the serviceKey values may not be blank.

When saving a new or updated service projection, pass the serviceKey of the referenced businessService structure.

UUID