UDDI Spec TC
1
2
Strawman Proposal - Representing
Property Information
3
4
5
Document identifier:
uddi-spec-tc-proposal-strawman-representing-property-information-2006-01-13.doc
6
7
Location:
TBD/uddi-spec-tc-proposal-strawman-representing-property-information-2006-01-13.doc
8
9
Authors:
Luc Clément, Systinet
10
Jason Garbis, Systinet
11
12
Editors:
13
14
Contributors:
15
16
17
18
Abstract:
This proposal describes how to represent property information in a UDDI registry in such a
way that its organizational structure is reusable, extensible, and easily searchable. It
illustrates this through several examples
19
20
21
22
The goal of this proposal is to engage the TC in the discussion of this topic, and to agree on
general guidelines for when to apply this design pattern, and how it should be applied.
Status:
This document is updated periodically on no particular schedule.
23
24
25
26
27
Committee members should send comments on this technical note to the [email protected] list. Others should subscribe to and send comments to the [email protected] list. To subscribe, send an email message to [email protected] with the word "subscribe" as the body of the
message.
28
29
30
31
For information on whether any intellectual property claims have been disclosed that may be
essential to implementing this technical note, and any offers of patent 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/).
32
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 1 of 13
33
34
35
36
37
38
Table of Contents
1
Introduction and Definitions..................................................................................................................... 3
1.1
Terminology ................................................................................................................................. 3
2
Technical note Solution ........................................................................................................................... 4
2.1
Requirements Scenario ............................................................................................................... 4
2.1.1
Assigning a Simple Property to an Entity ................................................................................................. 4
39
2.1.2
Creating a Logical Property Collection ..................................................................................................... 4
40
2.1.3
Reusing Logical Property Collections ...................................................................................................... 4
41
42
43
2.2
2.3
44
45
2.4
46
47
48
49
50
51
52
2.3.1
2.4.1
Shortcomings of General Keywords ............................................................................................. 5
Representing a Simple Property .................................................................................................. 5
Example: Simple Property : SecurityLevel ............................................................................................... 5
Representing a Logical Property Collection ................................................................................. 7
Representing a Logical Property Collection Attribute ............................................................................... 9
2.5
Reusing a Logical Property Collection ........................................................................................10
References.............................................................................................................................................12
3.1
Normative ...................................................................................................................................12
Appendix A. Acknowledgments......................................................................................................................12
Appendix B. Revision History .........................................................................................................................12
Appendix C. Notices ......................................................................................................................................12
3
53
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 2 of 13
54
1 Introduction and Definitions
55
56
57
58
59
The UDDI data model provides for the categorization of published entities, through the categoryBag
structure. Taxonomies referenced by the association with an entity give users of the registry the ability to
search, browse, and find entities according to a particular classification, which may be checked or
unchecked. An example of a checked taxonomy is the classification “US States”, which has a fixed set of 50
possible values. An example of an unchecked taxonomy is the classification “Fax Number”.
60
61
62
63
64
65
66
Some of this information may be thought of as expressing the categorization associated with an entity, while
other information may be thought of as the entity’s properties. The determination of what constitutes a
categorization, and what constitutes a property is more an art than a science – it’s dependent on technical
and business context, and on who is making the determination. The simplistic approach of treating checked
taxonomies as categorizations and unchecked as properties is unsatisfying, and arguably wrong in some
scenarios. For example, a service’s Security Level could easily be implemented as a checked taxonomy,
even though it is easily thought of as a property of the service.
67
68
69
In the end, the semantics of categorization versus property is irrelevant – this document’s goal is to
represent best practices for representing metadata in UDDI, and to illustrate this through several examples
of increasing complexity.
70
71
72
Clearly, the base UDDI spec provides the capability to associate arbitrary metadata with entities, through the
use of the predefined general_keywords categorization.( uddi-org:general_keywords ). The UDDI v3 spec
[UDDI3] Section 11.1.2 explains the General Keyword category:
73
74
75
76
77
Introduction: Usually, category systems in UDDI are defined by registering a new tModel
to represent the value set, but sometimes such formality is unnecessary. The UDDI
General Keywords Category System provides a way of informally defining any number of
unchecked value sets,each consisting of a namespace identifier and an associated set of
category values.
78
79
80
81
82
Design Goals : Provide a simple, lightweight means for establishing and using unchecked
UDDI category systems. Such value sets are generally fairly simple and often of interest
only to a small number of people. Checked value sets must, and complex or broadly
interesting value sets should be defined by registering a new tModel, which is the formal
means of documenting the meaning and intended use of a value set.
83
84
85
86
However, this Technical Note argues that general keywords should only be used under very limited
circumstances, and that the recommended approach is the creation of new categorization tModels to
represent properties. In addition, we explore some more advanced property-related scenarios, and make
recommendations about the approaches to address them
87
88
89
Note: The problem and the motivating use cases are described at [1] and [2]. In addition to these at
numerous other occasions the authors have been asked and has worked with vendors and practitioners to
address this specific need.
90
[1] http://lists.oasis-open.org/archives/uddi-spec/200503/msg00005.html
91
[2] http://lists.oasis-open.org/archives/uddi-dev/200503/msg00001.html
92
93
1.1
Terminology
94
95
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 [RFC2119].
96
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 3 of 13
97
2 Technical note Solution
98
2.1
Requirements Scenario
99
100
Associating additional metadata with a published UDDI entity is a core use case for UDDI. In this document,
we use three examples of increasing complexity to illustrate the recommended best practices.
101
102
103
The fictional Yoyodyne Systems (“Where the Future Starts Tomorrow!”) has embraced SOA for their internal
IT architecture, and is utilizing a UDDI registry as a key component of this. They have service-enabled many
of their existing systems, and are looking to enrich the metadata in their UDDI Registry.
104
2.1.1
105
106
107
Their first requirement is to provide a simple Security Level association with published services. They
currently support only the following levels of security, but anticipate needing to create additional levels as
their development progresses:
Assigning a Simple Property to an Entity
108

No Security
109

Encrypted Communications
110

Encrypted Communications and Username/Password Authentication
111
They need the ability to search & browse services by these properties in their UDDI console
112
113
2.1.2
Creating a Logical Property Collection
114
115
In addition, Yoyodyne has a highly distributed development environment, and wishes to associate contact
information with their services. They require the ability to store and manage
116

Contact Name
117

Contact Email Address
118

Contact Distinguished Name (for authoritative directory lookup)
119
120
The company would like to be able to treat these as a logically grouped collection of properties. Users must
be able to search on, browse by, and sort by these properties.
121
2.1.3
122
123
124
The IT architects also wish to associate different kinds of contact information with services. Specifically, they
need to be able to decorate a service with contact information for the operational support contact, the
developer of the service, and the release manager responsible for the QA of the service.
125
They have identified the following set of contact information, which they wish treated as a logical group.
Reusing Logical Property Collections
126

Name
127

Email Address
128

Distinguished Name
129
130
131
They also wish to be able to reuse this logical group as a data structure, for both of the relationships outlined
above. In addition, they anticipate needing to represent other contact relationships such as “consumes” in
the future.
132
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 4 of 13
133
2.2
Shortcomings of General Keywords
134
135
While in theory General Keywords could be used to represent simple property information, it suffers from a
number of shortcomings that make it a poor solution to meet these needs.
136
137
138
139
140
141
First of all, because General Keywords are unconstrained, any string can be used as a key name or key
value. This makes it very difficult for users to search for the set of matching entities, since they would need
to know the set of valid keys in order to search – and, by definition, the set of valid key names is not
formally defined anywhere within the UDDI system. Likewise, the set of values are unconstrained, and
undefined. There is also no facility to associate additional metadata with the general keyword namespace –
no equivalent to the OverviewDoc associated with other UDDI structures.
142
143
144
Beyond these limitations, the general keywords approach also falls short in the area of creating logical
property collections, as described above. Users cannot create logical collections of properties (such as the
contact information example above), which also eliminates the ability to reuse such collections.
145
146
Therefore, we recommend the use of standard tModel-based categorizations to represent properties, as
described below.
147
2.3
148
149
150
The recommended approach to represent a simple property is through a standard UDDI categorization,
defined in a tModel. This enables a rich expression of the categorization, the ability to restrict to a fixed value
set, and the ability to associate additional human-readable documentation with the property.
151
2.3.1
152
tModel Definition
Representing a Simple Property
Example: Simple Property : SecurityLevel
Name
yoyodyne-com:property:security:level
Description
Yoyodyne’s service security level
UDDI Key (V3)
uddi:yoyodyne-com:property:security:level
UDDI V1,V2 format
key
TBD
Categorization
categorization
Checked
Yes
153
154
tModel Structure
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<?xml version="1.0" encoding="UTF-8"?>
<tModel tModelKey=" uddi:yoyodyne-com:property:security:level" xmlns="urn:uddi-org:api_v3">
<name>yoyodyne-com:property:security:level</name>
<description xml:lang="en">Categorization defining the security level implemented by the service.
This is a checked value set, and is restricted to the valid set of Yoyodyne security levels.
</description>
<overviewDoc>
<overviewURL useType="text">http://internal.yoyodyne.com/securitylevels</overviewURL>
</overviewDoc>
<categoryBag>
<keyedReference tModelKey="uddi:uddi.org:categorization:types"
keyName="uddi-org:types:categorization"
keyValue="categorization"/>
</categoryBag>
</tModel>
170
171
Valid Values
172
This is a checked value set, with valid values:
173

None
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 5 of 13
174

EncryptedComms
175

EncryptedCommsPasswordAuth
176
177
178
179
180
181
182
Example of Use
<categoryBag>
…
<keyedReference tModelKey="uddi:yoyodyne-com:property:security:level"
keyName="Security Level"
keyValue="EncryptedComms"/>
</categoryBag>
183
184
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 6 of 13
185
2.4
Representing a Logical Property Collection
186
187
In many cases, a single logical property actually consists of several attributes. For example, an Address
property may be made up of Name, Street address, City, State, and Postal Code attributes.
188
By representing this collection as a UDDI Keyed Reference Group, users can query for matching attributes.
189
The tModel definition for an organizational contact category system could be defined as follows:
190
tModel Definition
Name
Yoyodyne.com:organizationalContact
Description
A categorization group tModel, used to represent contacts within the
organization.
This group is intended to be used as a container for the following contact
information:

Contact name
(via the uddi:yoyodyne-com:property:contact:name tModel)

Contact Email
(via uddi:yoyodyne-com:property:contact:email:smtp)

Contact Distiguished Name
(via uddi:yoyodyne-com:property:contact:dn)
This is an unchecked categorization group
UDDI Key (V3)
uddi:yoyodyne-com:property:organizationalcontact
UDDI V1,V2 format
key
TBD
Categorization
categorizationGroup
Checked
no
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
tModel Structure
<?xml version="1.0" encoding="UTF-8"?>
<tModel tModelKey="uddi:yoyodyne-com:property:organizationalcontact" xmlns="urn:uddi-org:api_v3">
<name>yoyodyne-com:organizationalContact</name>
<description xml:lang="en">A categorization group, intended to represent organizationalContacts,
consisting of the following attributes: a contact name (via the uddi:yoyodne-com:property:contact:name
tModel), a contact email (via the uddi:yoyodyne-com:property:contact:email:smtp), and a contact's
distinguished name (via the uddi:yoyodyne-com:property:contact:dn tModel). This information can be
applied to any UDDI core entity element.</description>
<overviewDoc>
<overviewURL useType="text">TBD</overviewURL>
</overviewDoc>
<categoryBag>
<keyedReference tModelKey="uddi:uddi.org:categorization:types"
keyName="uddi-org:types:categorization"
keyValue="categorizationGroup"/>
</categoryBag>
</tModel>
Valid Values
211
212
213
This is an unchecked value set. It is intended to represent organizationalContacts, consisting
of the following attributes:
a contact name (via the uddi:yoyodne-com:property:contact:name tModel)
214
a contact email (via the uddi:yoyodyne-com:property:contact:email:smtp)
215
a contact's distinguished name (via the uddi:yoyodyne-com:property:contact:dn tModel).
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 7 of 13
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
This information can be applied to any UDDI core entity element.
Example of Use
<categoryBag>
…
<keyedReferenceGroup tModelKey="uddi:yoyodyne-com:property:organizationalcontact">
<keyedReference tModelKey="uddi:yoyodyne-com:property:contact:name"
keyName="Name"
keyValue="John Bigboote"/>
<keyedReference tModelKey="uddi:yoyodyne-com:property:contact:email:smtp"
keyName="Email"
keyValue="[email protected]"/>
<keyedReference tModelKey="uddi:yoyodyne-com:property:contact:dn"
keyName="Contact Distinguished Name"
keyValue="cn=John Bigboote,ou=IT Services,o=Company,dc=yoyodyne,dc=com"/>
</keyedReferenceGroup>
</categoryBag>
233
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 8 of 13
234
235
2.4.1
Representing a Logical Property Collection Attribute
236
237
Each of the Keyed Reference Group’s attributes are represented as a standard UDDI Categorization, which
is intended to be used only within the associated keyed reference group.
238
239
240
For example, an organizational contact’s SMTP Mail address would be represented through a
categorization. This categorization is intended to be used within the yoyodyne-com:organizationalContact
categorization group. The SMTP email address would be reified as :
241
242
tModel Definition
Name
yoyodyne-com:property:contact:email:smtp
Description
SMTP mail address of an organizational contact
UDDI Key (V3)
uddi:xxx-org:property:contact:email:smtp
UDDI V1,V2 format
key
TBD
Categorization
categorization
Checked
no
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
tModel Structure
<?xml version="1.0" encoding="UTF-8"?>
<tModel tModelKey="uddi:yoyodyne-com:property:contact:email:smtp" xmlns="urn:uddi-org:api_v3">
<name>yoyodyne-com:property:contact:email:smtp</name>
<description xml:lang="en">SMTP mail address of an organizational contact.</description>
<overviewDoc>
<overviewURL useType="text">TBD</overviewURL>
</overviewDoc>
<categoryBag>
<keyedReference tModelKey="uddi:uddi.org:categorization:types"
keyName="uddi-org:types:categorization"
keyValue="categorization"/>
</categoryBag>
</tModel>
Valid Values
259
260
261
262
263
264
265
266
267
268
269
270
This is an unchecked value set.
Example of Use
<categoryBag>
…
<keyedReferenceGroup tModelKey="uddi:yoyodyne-com:property:organizationalcontact">
…
<keyedReference tModelKey="uddi:yoyodyne-com:property:contact:email:smtp"
keyName="Email"
keyValue="[email protected]"/>
…
</keyedReferenceGroup>
</categoryBag>
271
272
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 9 of 13
273
2.5
Reusing a Logical Property Collection
274
275
276
277
278
279
280
Frequently, a logical properly collection is created in order to be reused – that is, the organization wishes to
apply the group of attributes multiple times, with a distinct relationship to the containing entity each time.
Although the logical property collection is made up of the same set of attributes, the quality of the
relationship differs. For example, the Contact collection described above may need to be associated with a
Service multiple times – once for the Developer of the service, once for the Operator, and once for the
Release Manager. Although each of these contacts have the same fields, they each have a different
relationship with the service – and this relationship must be qualified in the property collection.
281
282
Reusing a logical property collection (with a relationship attribute) provides a consistent approach to the
general Contact concept, and the ability to easily extend with new types of contacts.
283
284
285
This relationship should be reified as a categorization tModel, intended to be used as part of the containing
logical property collection. This relationship is intended to be a qualifying attribute of the logical property
collection.
286
287
This should be a checked taxonomy, to restrict the set of relationships to the fixed set of value appropriate
for the operating organization.
288
Example tModel Definition
Name
yoyodyne-com:relationship:contact
Description
Category system used to declare a relationship of a contact with a UDDI
entity
UDDI Key (V3)
uddi:yoyodyne-com:relationship:contact
UDDI V1,V2 format
key
TBD
Categorization
categorization
Checked
yes
289
290
tModel Structure
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
<tModel tModelKey="uddi:yoyodyne-com:relationship:contact">
<name>yoyodyne-com:relationship:contact</name>
<description>Category system used to declare a relationship of a contact with a UDDI
entity</description>
<overviewDoc>
<overviewURL useType="text">TBD</overviewURL>
</overviewDoc>
<categoryBag>
<keyedReference tModelKey="uddi:uddi.org:categorization:types"
keyName="uddi-org:types:categorization"
keyValue="categorization"/>
<keyedReference tModelKey="uddi:uddi.org:categorization:types"
keyName="uddi-org:types:checked"
keyValue="checked" />
</categoryBag>
</tModel>
Valid Values
308
The valid set of values for this category system is:
309

yoyodyne-com:relationship:contact:developer
310

yoyodyne-com:relationship:contact:operator
311

yoyodyne-com:relationship:contact:release-manager
312
313
Example of Use
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 10 of 13
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
The example below associates a developer contact with the eBayWatcherBrokeredITService
<businessService serviceKey="uddi:e21b09d0-2f8c-11d9-95fe-a551675095fd"
businessKey="uddi:97b8a160-2eb8-11d9-95fd-a551675095fd" xmlns="urn:uddi-org:api_v3">
<name>eBayWatcherBrokeredITService</name>
<bindingTemplates>
<bindingTemplate bindingKey="uddi:e23aede0-2f8c-11d9-95fe-a551675095fd"
serviceKey="uddi:e21b09d0-2f8c-11d9-95fe-a551675095fd">
<accessPoint useType="endPoint">
http://myendpoint/sd/eBayWatcherBrokeredITService</accessPoint>
<tModelInstanceDetails>
<tModelInstanceInfo tModelKey="uddi:e1fb73e0-2f8c-11d9-95fe-a551675095fd">
<instanceDetails>
<instanceParms>eBayWatcherPortTypePort</instanceParms>
</instanceDetails>
</tModelInstanceInfo>
<tModelInstanceInfo tModelKey="uddi:dfb44300-2f8c-11d9-95fe-a551675095fd"/>
</tModelInstanceDetails>
</bindingTemplate>
</bindingTemplates>
<categoryBag>
<keyedReferenceGroup tModelKey="uddi:yoyodyne-com:property:organizationalcontact">
<keyedReference tModelKey=" uddi:yoyodyne-com:relationship:contact "
keyName="Developer"
keyValue="yoyodyne-com:relationship:contact:developer”/>
338
339
340
341
342
343
344
345
346
347
348
349
<keyedReference tModelKey="uddi:yoyodyne-com:property:contact:name"
keyName="Name"
keyValue="John Bigboote"/>
<keyedReference tModelKey="uddi:yoyodyne-com:property:contact:email:smtp"
keyName="Email"
keyValue="[email protected]"/>
<keyedReference tModelKey="uddi:yoyodyne-com:property:contact:dn"
keyName="Contact Distinguished Name"
keyValue="cn=John Bigboote,ou=IT Services,o=Company,dc=yoyodyne,dc=com"/>
</keyedReferenceGroup>
</categoryBag>
</businessService>
350
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 11 of 13
351
3 References
352
353
354
355
[This section should list any references to publicly available documents that the reader may find helpful
during reading of this Technical noted document. These documents may expand upon any aspect of the
material, for instance they may provide additional insight into the business situation dealt with or they may
document standards or products used in developing the solution.]
356
3.1
357
358
[RFC2119]
S. Bradner, Key words for use in RFCs to Indicate Requirement Levels,
http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
359
360
[UDDI3]
Normative
http://uddi.org/pubs/uddi-v3.0.2-20041019.htm
361
Appendix A. Acknowledgments
362
The following individuals were members of the committee during the development of this technical note:
363
Appendix B. Revision History
364
[This appendix is optional, but helpful.]
Rev
Date
By Whom
What
0.1
2005-03-20
L. Clément
Initial Draft
0.2
2006-01-13
J. Garbis
Revised Draft
365
366
367
Appendix C. Notices
368
369
370
371
372
373
374
375
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might
be claimed to pertain to the implementation or use of the technology described in this document or the
extent to which any license under such rights might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in
OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for
publication and any assurances of licenses to be made available, or the result of an attempt made to obtain
a general license or permission for the use of such proprietary rights by implementors or users of this
specification, can be obtained from the OASIS Executive Director.
376
377
378
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or
other proprietary rights which may cover technology that may be required to implement this specification.
Please address the information to the OASIS Executive Director.
379
Copyright © OASIS Open 2006. All Rights Reserved.
380
381
382
383
384
385
This document and translations of it may be copied and furnished to others, and derivative works that
comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and
this paragraph are included on all such copies and derivative works. However, this document itself may not
be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed
for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 12 of 13
386
387
the OASIS Intellectual Property Rights document must be followed, or as required to translate it into
languages other than English.
388
389
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or
assigns.
390
391
392
393
This document and the information contained herein is provided on an “AS IS” basis and OASIS
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR
ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
394
395
396
397
81922577
Copyright © OASIS Open 2005. All Rights Reserved.
Page 13 of 13