UDDI Spec TC

Technical Note

Value Set Overview Documents

Document identifier:

uddi-spec-tc-tn-valuesetoverviewdocument-20040316

Current Version:

http://www.oasis-open.org/committees/uddi-spec/doc/tn/uddi-spec-tc-tn-valuesetoverviewdocument-20040316.htm

Latest Version:

http://www.oasis-open.org/committees/uddi-spec/doc/tn/uddi-spec-tc-tn-valuesetoverviewdocument.htm

Author:

Max Voskob

Editors:

Luc Clément

Tony Rogers, Computer Associates

Abstract:

Value sets facilitate discovery of entities in UDDI registries. Value sets may consist of various types of values and hierarchies that may not always be self-explanatory, e.g. value sets consisting of codes or numbers. It is thus important that value sets be well-understood by their users and applied correctly and consistently to improve the quality of registration of entities and facilitate their discovery.

This OASIS UDDI Spec TC Technical Note provides recommendations on what Value Set Overview Documents accompanying a value set need to contain. Application of this TN will ensure consistency and completeness of Value Set Overview Documents.

Status:

This document is updated periodically on no particular schedule. Send comments to the editors.

Committee members should send comments on this technical note to the uddi-spec@lists.oasis-open.org list. Others should submit comments via http://www.oasis-open.org/committees/comments/form.php?wg_abbrev=uddi-spec.

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/).


Table of Contents

1      Definitions. 2

2      Requirements of a value set overview Document 2

2.1 Application of the value set 3

2.2 tModel definition. 3

2.3 tModel structure. 3

2.4 Valid values. 3

2.5 Structure. 4

2.6 Examples. 4

2.7 How to obtain the value set and related information. 4

2.8 Optional Information. 5

3      Template. 5

4      References. 5

4.1 Normative. 5

Appendix A. Acknowledgments. 6

Appendix B. Revision History. 7

Appendix C. Notices. 8

 

1        Definitions

Value Set

Classification and identification systems, taken together, are called “value sets” in UDDI. Value sets may be “checked” or “unchecked”. Both checked and unchecked value sets are used for categorization and identification. The difference between them is that whenever a checked value set is used, the use is inspected to see that it conforms to the restrictions of the value set. Uses of unchecked value sets are not checked. [UDDIV3]

Value Set Overview Document

A document describing a value set for users.

2        Requirements of a value set overview Document

This section outlines the minimal requirements for the contents of a Value Set Overview Document.  Section 3 provides templates that can be used as a starting point when authoring an overview document.

 

An overview document should present a quick overview so that users can quickly decide on the relevance of the value set to their application. Providing links to applying documentation is recommended. The author of the overview document should consider limiting the size of the overview document to ensure timely download of its content; this TN recommends a maximum of 0.2MB in size.

 

An overview document that conforms to this TN MUST contain the following sections.

2.1 Application of the value set

The Value Set Overview Document:

·         MUST provide a brief introduction discussing the purpose of the value set, and where and how it can be applied.

Optionally:

·         MAY list possible applications and field of use, e.g. where the value set is considered to add value to the discovery process.

·         MAY specify any special circumstances when use of the value set is not recommended.

2.2 tModel definition

The Value Set Overview Document MUST fully describe the tModel, including:

·         tModel Name

·         tModel Description

·         Overview Document URL

·         v2 tModel Key

·         v3 tModel Key

·         Categorization

·         Checked/Un-checked

 

See [uddi.org tModels] for more information on registering tModels.

2.3 tModel structure

The Value Set Overview Document MUST include the full tModel structure in XML.

2.4 Valid values

The Value Set Overview Document MUST describe the valid values of the value set:

·         If there are few valid values, then list them.

·         If there are more than a few valid values, then the Value Set Overview Document SHOULD specify a URL to an external resource with the values. If the format of the data which documents the valid values is other than simple text, then the format used MUST be identified.

·         If there is no predefined list of values and the values are computable, then the Value Set Overview Document SHOULD specify the algorithm, or give information on how to obtain or validate the values. The document MUST provide URLs if any of this information is external.

 

Additionally:

·         If any of the values need comments, usage instructions, or any other additional information that may be considered useful for the application of the value set, then the Value Set Overview Document SHOULD give a URL to an external resource with that information.

·         If the validation service is provided by the author, the Value Set Overview Document MUST provide detailed information on:

·         supported validating capabilities

·         validation APIs

·         caching of valid values

 

In regard to versioning, the Value Set Overview Document SHOULD:

·         provide information on the versioning rules for the value set

·         state explicitly that the value set conforms to the [Versioning Value Sets] TN

·         provide a list of all supported versions

2.5 Structure

The Value Set Overview Document MUST:

·         Provide a brief overview of the structure of the value set, e.g. if it is a set of disparate values or forms a hierarchy, network, clusters, etc.

·         Describe any special structure inherent in the actual values themselves. E.g. partitioned values such as UDDI keys, URNs, etc.

·         Include any special structural information that is part of this value set that may affect the construction of effective inquiries.

 

For value sets with relationships between elements (values), the publisher MUST:

·         explain the relationship mechanism, e.g. what XML attributes are used as IDs or pointers; or

·         provide a plain language description or a diagram of the relationships between the elements (values).

2.6 Examples

The Value Set Overview Document MUST provide at least one example of use of the value set. The example SHOULD be an XML excerpt illustrating the use of <categoryBag> or <identifierBag> with values from the value set.

 

If there is any special structural information that is part of this value set, examples SHOULD be provided which illustrate how one efficiently makes queries using this value set.  This SHOULD include how best to leverage the use of approximateMatch behavior in V3 registries. 

2.7 How to obtain the value set and related information

The Value Set Overview Document MUST:

·         provide clear instructions on where and how to obtain the value set, including URLs for every external resource listed in the overview document.

·         provide sufficient information about the format of each resource so that users can parse and understand the content and relationships of the value set.

 

As appropriate, the document SHOULD:

·         provide conditions of use, such as any requirement for registration, payment, or a legal agreement before access to any of the resources

·         provide a statement regarding Intellectual Property Rights (including copyright) affecting use of the value set, validation routines or validation API, including licensing requirements, etc.

2.8 Optional Information

Include any optional information not covered by the required sections above, if applicable.

3        Template

Value Set authors may use the following template to simplify creation of Value Set Overview Documents: http://www.oasis-open.org/committees/uddi-spec/doc/tn/uddi-spec-tc-valueset-overviewdocument-template20040316.htm.

 

It is highly recommended that HTML be used as the document format for Value Set Overview Documents.

4        References

4.1 Normative

[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.

[Versioning Value Sets]      Versioning Value Sets in a UDDI Registry, Version 1.12, OASIS UDDI Spec TC Technical Note, http://www.oasis-open.org/committees/uddi-spec/doc/tn/uddi-spec-tc-tn-versioning-value-sets.htm

 

[UDDIV3]                L. Clément et al, UDDI Version 3.0 Specification, http://uddi.org/pubs/uddi_v3.htm.

 

[uddi.org tModels]  common tModels published on uddi.org website
http://www.uddi.org/tmodels.html


 

Appendix A. Acknowledgments

The following individuals were members of the committee during the development of this technical note:

Tom Bellwood, IBM

Maud Cahuzac, France Télécom

Luc Clément, Microsoft

Daniel Feygin, UnitSpace

Rajul Gupta, OSS Nokalva

Andrew Hately, IBM

Brad Henry

Paul Macias, LMI

Claus von Riegen, SAP

Tony Rogers, Computer Associates

Paul Thorpe, OSS Nokalva


 

Appendix B. Revision History

 

Rev

Date

By Whom

What

0.1

20031013

Max Voskob

Initial draft

0.2

20031028

TC FTF

Review

0.3

20031029

Max Voskob

Changes in the response to the review

0.4

20031109

Max Voskob

Various modifications and formatting

0.5

20031207

Tony Rogers

Proof reading / tidying up of language

0.6

20040104

Luc Clément

Further editorial updates

1.0

20040316

Luc Clément

Final editorial updates


 

Appendix C. Notices

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.

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.

Copyright © OASIS Open 2004. All Rights Reserved.

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 the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

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.