OASIS Specification Template Guidelines

[specifications replaced by this standard - OASIS as well as other standards organizations]

[specifications related to this standard - OASIS as well as other standards organizations]

This document was created using the HTML template (OASISSpecificationTemplateV3.0.html) and is intended to serve as documentation of its usage.

The following text is boilerplate and is not to be modified in any way, other than supplying the appropriate information in the areas indicated by open / close square brackets, without explicit permission of the TC Administrator.

This document was last revised or approved by the [TC name | membership of OASIS] on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document.

Technical Committee members should send comments on this specification to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the “Send A Comment” button on the Technical Committee’s web page at www.oasis-open.org/committees/[specific location].

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page ( www.oasis-open.org/committees/[specific location]/ ipr.php.

The non-normative errata page for this specification is located at www.oasis-open.org/committees/[specific location].

Notices

The Notices section below is boilerplate and must not be modified in way, other than supplying the appropriate information in the areas indicated by open / close square brackets

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

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 section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, 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 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

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' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on 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 implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The names “OASIS”, [insert specific trademarked names, abbreviations, etc. here] are trademarks of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.

[build table of contents here. Should list at least 3 levels (sections numbered x.x.x) which are hyperlinked to the actual section.]

1. Introduction

The XHTML Specification template consists of boilerplate text and hints to assist specification editors in preparing documents conforming to the OASIS standard style. An aditional file, the CSS stylesheet, must be used in conjunction with the XHTML template. This allows easy modification of the styles without having to edit each individual document. Similar templates are provided for use with Microsoft Word and Open Office.

1.1 Terminology

The key words words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in [RFC2119].

1.2 Normative References

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

[Reference]

[Full reference citation]

1.3 Non-Normative References

[Reference]

[Full reference citation]

2. Installing and Using the XHTML Template

2.1 Installation

Please follow the specific directions for the XHTML editor of choice. In general, download both the XHTML template file (http://docs.oasis-open.org/templates/OASIS_Specification_Template_v3-0.html) and the CSS stylesheet file (OASIS_Specification_Template_v1-0.css). The location of the stylesheet is hard-coded in the template document (http://docs.oasis-open.org/templates/css/OASIS_Specification_Template_v1-0.css); you may need to change the reference while working in your local environment. Please be sure to change the reference once you have submitted your document to be uploaded onto the OASIS website.

2.2 Usage

There are three major components to the OASIS Specification template: placeholder text or hints,
boilerplate text, and document styles.

2.2.1 Placeholder Text

Much of the template makes use of placeholder text, indicated by open ([)and close (]) square brackets. This text is to be replaced with the actual content.

2.2.2 Boilerplate Text

Boilerplate text is automatically incorporated into the template and should not be modified, except as noted by placeholder text.

2.2.3 Document Styles

The XHTML template makes use of a Cascading Style Sheet (CSS) to automatically apply stylistic formatting to the document instance. The stylesheet has a permanent home at http://docs.oasis-open.org/templates/css/OASIS_Specification_Template_v1-0.css.

3 Front Matter

The front matter contains a significant amount of metadata that must be supplied by the document editor(s) in accordance with the OASIS Guidelines for Filenames, URIs, Namespaces, and Metadata. Each item below is linked to the specific section in the policy document for reference.

The front matter also contains an abstract as well as the status of the document itself.

3.1 Specification Title

Insert the title of the document followed by "Version" and the specific version number. title version

3.2 Stage and Revision

The document stage refers to one of the following document states: Working Draft, Committee Draft, Committee Specification, or OASIS Standard. Each stage, other than OASIS Standard, must be followed by a two-digit identifier (i.e. Committee Draft 01, Committee Draft 02, etc.) stage

A Revision represents a specification instance higher than Working Draft stage which has not been formally approved by TC vote. it is indicated by the word "Revision" followed by a two-digit identifier (i.e. Committee Draft 01 Revision 01). revision

3.3 Date

The date must correspond to the date the particular stage was approved by TC or OASIS membership vote, or in the case of a Working Draft or Revision the date last issued. The date must be in the format DD Month YYYY (i.e. 1 January 2007). date

3.4 Specification URIs

Specifications must list at least three URIs for each document: This Version, Previous Version, and Latest Version. If the specification being published has not been approved by the membership, then a fourth URI specifying Latest Approved Version should also be provided. All specifications are assigned a URI in the form of http://docs.oasis-open.org/docs/[tc_short_name]/[additional path/filename]. URIs

3.4.1 This Version

A version-specific URI which is persistent, permanently assigned to one particular specification instance, and never re-used.

3.4.2 Previous Version

A version-specific URI used to reference the previous published instance.

3.4.3 Latest Version

A bookmarkable, version-agnostic, generic URI serving as a URI alias which is always associated with the latest/current specification instance.

3.4.4 Latest Approved Version

The previous version is meant to refer to the most recent previous version. (http://docs.oasis-open.org/docs/[tc_short_name]/[spec]/[previous_version]). A URI which identifies the most recent published instance of a specification formally approved by a TC through ballot/vote.

3.5 Technical Committee

The full name of the technical committee that produced the document. The name of the TC should be hyperlinked to the TC Public Home Page, i.e. http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=[tc-shortname] technical committee

3.6 Chair(s):

The name or names of the committee chair or chairs. If the chair(s) are organizational members, their corporate affiliation may be noted following their name. If the chair(s) are individual or associate members, no affiliation may be displayed. chair

3.7 Editor(s):

The name or names of the specification editor or editors. If the editor(s) are organizational members, their corporate affiliation may be noted following their name. If the editor(s) are individual or associate members, no affiliation may be displayed. editor

3.8 Related Work:

List any and all standards, whether created by an OASIS technical committee or other standards organization, that are replaced or superceded by this document. Also list any related work, whether created by an OASIS technical committee or other standards organization. related work

3.9 Declared Namespaces:

List any and all namespaces declared by the specification. Note that namespaces must resolve to some informative resource. namespaces

3.10 Abstract:

The abstract should include a brief problem statement, the scope of the solution, the intended audience, and a short overview of the specification. It should not be longer than a few paragraphs. abstract

3.11 Status:

The Status section consists of boilerplate text that should not be changed, other than the reference in the first line to either the TC name or OASIS membership and the specific references to the TC website. The last paragraph pertaining to errata may be omitted if there is no such document. errata

7 Styles

Styles are collections of raw formatting codes that facilitate consistent application of formatting characteristics throughout a document instance. Use of direct formatting should be avoided whenever possible.

7.1 Overall Style

The template is intended to create a single document instance with hypertext navigation rather than a series of smaller web pages. By default, the typeface used is Arial 10pt. While line numbers are included in the Microsoft Word and OpenOffice templates, they are not used in the XHTML version.

7.2 Front Matter

The Title Page contains a significant amount of information about the Specification Document. This metadata serves to quickly identify key information about a specification and will be used to populate the OASIS Registry. Most of the information to be entered on the Title Page is done through the use of placeholder text. Styles used on the Title Page include the following (in order of appearance):

.title

.subtitle

.titlepageinfo

.titlepageinfodescription

.relatedwork

.abstract

7.3 Headings

There are three sets of Heading styles: undesignated, arabic designation, and alphabetic designation. The style names are consistent throughout the three supported applications, although their output is slightly different due to capabilities and limitations. Title, Notices and Subtitle are used in the front matter and carry no designation. Heading1 through Heading 9 are used throughout the body of the document and are intended to follow a legal style of numbering, but numbers must be manually added due to current lack of support for CSS2. AppendixHeading1 through AppendixHeading3 are similar to Heading 1 through Heading 3, but use Alphabetic designations (again, the designations must be manually applied).

7.4 Paragraphs

The basic paragraph style for the body of the document is Normal. The Normal style is set to 10 pt Arial, with 4pt of extra lead between paragraphs.

7.5 Lists

There are several styles associated with lists: Definition, Ref, List Bullet, and List Continue.

7.5.1 Definition Lists

The Definition term and Definition paragraph styles produce a definition list with a hanging indent. Pressing Return after one inserts the other directly after.

Definition term

Definition for the term.

7.5.2 Reference Lists

For bibliography lists, use the Ref paragraph style. Use the Ref term character style for the bracketed text that serves as the bibliography entry key, and make each reference term into a bookmark for use as references from the text. For example, [RFC2119] is a generated cross-reference to the IETF RFC 2119 bibliography entry in Section 1.2 of this sample.

7.5.2.1 Creating Internal Hypertext Links

7.5.3 Bulleted Lists

There are two levels of unordered lists: List Bullet and List Bullet 2. Use List bullet for first-level bulleted lists. Use List bullet 2 for second-level bulleted lists. Use List continue for multiple paragraphs in list items.

• List bullet

List continue.

– List bullet 2

List continue 2.

7.6 Tables

Xxx

7.7 Graphics / Figures

7.8 Code Examples

For schema code and other normative code, use the Code paragraph style. It fits 71 characters.

For example:

12345678901234567890123456789012345678901234567890123456789012345678901
1 2 3 4 5 6 7
<simpleType name="DecisionType">
<restriction base="string">
<enumeration value="Permit"/>
<enumeration value="Deny"/>
<enumeration value="Indeterminate"/>
</restriction>
</simpleType>

Use the Code small style if the code has very long lines. It fits 80 characters. For example:

12345678901234567890123456789012345678901234567890123456789012345678901234567890
1 2 3 4 5 6 7 8
<simpleType name="DecisionType">
<restriction base="string">
<enumeration value="Permit"/>
<enumeration value="Deny"/>
<enumeration value="Indeterminate"/>
</restriction>
</simpleType>
See Appendix C for non-normative code examples.

7.9 Character Styles

This template defines several character styles for general text use:

.attribute

.codetemp

.datatype

.element

.emphasis

.keyword

.refterm

.variable

Revision	Date	Editor	Changes Made