|
UDDI Spec TC |
Technical Note
Value Set Overview Documents
Document
identifier:
uddi-spec-tc-tn-valuesetoverviewdocument-20040316
Current Version:
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
2 Requirements of a value set overview Document
2.1 Application of the value set
2.7 How to obtain the value set and related information. 4
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.
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.
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.
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.
The Value Set Overview Document MUST include the full tModel structure in XML.
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
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).
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.
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.
Include any optional information not covered by the required sections above, if applicable.
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.
[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
The following individuals were members of the committee during the development of this technical note:
Tom Bellwood, IBM
Maud
Luc Clément, Microsoft
Daniel Feygin, UnitSpace
Rajul Gupta,
Andrew Hately, IBM
Brad Henry
Paul Macias, LMI
Claus von Riegen, SAP
Tony Rogers, Computer Associates
Paul Thorpe,
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 |
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.