Guidelines to Writing Conformance Clauses
4 September 2007
Table of Contents
1 Introduction
2 Terms and Definitions
3 Conformance Keywords
4 Normative Statements
5 Conformance Section and Clauses
6 Checklist
Effective from 1 June 2007, the OASIS TC Process requires that each specification contain a separate Conformance section listing the Conformance Clauses that need to be observed by implementers or users of the specification in order to claim successful use of a specification.
This document provides guidelines on how to write Conformance statements for OASIS specifications. While it is not a requirement to follow these guidelines, it is recommended that TC adopt the advice herein in order to achieve consistency across OASIS specifications. The topic of Conformance testing, covering validation of implementations with respect to a specification,is not covered in these guidelines.
The target audience is primarily specification writers and TC members.
This document describes the purpose and scope of Conformance Clauses, and associated issues that Conformance Clauses shall address. Wherever possible, sample text and examples will be given.
The information contained is produced as the result of extensive experience by OASIS Staff and TAB Members in the writing and reviewing of specifications, and draws upon guidelines and requirements from ISO/IEC, IEEE, W3C, WS-I and OASIS.
IEEE http://www.ietf.org/rfc/rfc2119.txt
ISO/IEC ISO/IEC Guide 2:2004 Standardization and related activities – General vocabulary (not free)
ISO/IEC ISO/IEC Directives Part 2: Rules for the structure and drafting of International Standards
OASIS http://www.oasis-open.org/committees/download.php/305/conformance_requirements-v1.pdf
W3C http://www.w3.org/TR/qaframe-spec/
WS-I http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#conformance
For the purposes of this document and specifications implementing this document, the following relevant terms and definitions apply:
Conformance – the fulfillment of specified requirements by a product, document, process, or service
Conformance Claim – a declaration that a product or artifact meets the requirements of one or more Conformance Clauses. A Conformance claim SHOULD accompany a statement of use declaration when a Committee Specification is being advanced to OASIS Standard.
Conformance Clause – A statement in the Conformance section of a specification that provides a high-level description of what is required for an artifact to conform. It, in turn, refers to other parts of the specification for details. A Conformance Clause must reference one or more Normative Statements, directly or indirectly, and may refer to another Conformance Clause.
Conformance Target – an artifact such as a protocol, document, platform, process or service, which is the subject of Conformance Clauses and Normative Statements. There may be several Conformance Targets defined within a specification, and these targets may be diverse so as to reflect different aspects of a specification. For example, a protocol message and a protocol engine may be different targets.
Normative Statement – a statement made in the body of a specification that defines prescriptive requirements on a Conformance Target.
When writing Normative Statements and Conformance Clauses, specific keywords must be used throughout the specification to denote whether or not requirements are mandatory, optional, or suggested. Using a standard set of key word helps to easily identify the Normative Statements and Conformance Clauses.
OASIS specifications SHOULD use the following keywords from IETF RFC 2119. This is the default terminology to be used in all OASIS specifications. The definitions from RFC 2119 are given below, and have been simplified to highlight all the keywords:
MUST - the requirement is an absolute requirement of the specification.
MUST NOT – the requirement is an absolute prohibition of the specification
REQUIRED – see MUST
SHALL – see MUST
SHALL NOT – see MUST NOT
SHOULD – there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
SHOULD NOT – there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
RECOMMENDED – see SHOULD.
MAY - the item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation that does not include a particular option MUST be prepared to interoperate with another implementation that does include the option, though perhaps with reduced functionality. In the same vein an implementation, which does include a particular option MUST be prepared to interoperate with another implementation that does not include the option (except, of course, for the feature the option provides).
While RFC2119 permits the use of synonyms, to achieve consistency across specifications it is recommended that MUST be used instead of SHALL, and MUST NOT instead of SHALL NOT.
RFC2119 allows both uppercase and lowercase to be used for a keyword, however to enable easy identification of the keywords and consistency across specifications uppercase MUST be used for keywords at all times.
Alternative keywords
Some OASIS specifications are intended for advancement to other bodies such as ISO/IEC and ITU-T. In those cases it is permissible to use the ISO keywords instead of the default RFC 2119 ones. A specification that makes use of ISO keywords MUST explicitly declare this in the specification.
Under no circumstances SHOULD RFC 2119 or ISO styles be used in the same documents.
A re-presentation of the ISO keywords are:
SHALL – to indicate requirements strictly to be followed in order to conform to the standard and in which no deviation is permitted. Equivalent expressions include: is to, is required to, has to, it is necessary. Do not use MUST as an alternative for shall.
SHALL NOT - converse of SHALL.
SHOULD – to indicate that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others.
SHOULD NOT – converse of SHOULD.
MAY – to indicate a course of action permissible within the limits of the standard. Equivalent expressions include: is permitted, is allowed.
NEED NOT – to indicate a course of action is not required.
CAN – statement of possibility and capability, whether material, physical, or causal. Equivalent expressions include: be able to, it is possible to.
CANNOT – converse of CAN.
A specification broadly consist of descriptive text and Normative Statements. The Normative Statements define what a Conformance Target MUST do to adhere to that part of the specification, and the descriptive text provides background information, descriptions and examples. Descriptive text is not normative and is used to provide contextual information. Normative statements are those that use the RFC2119 keywords (or the ISO keywords if these have been chosen instead), descriptive text does not use these reserved words as keywords.
The following example is taken from the WS-BPEL specification:
WS-BPEL supports extensibility by allowing namespace-qualified attributes to appear on any WS-BPEL element and by allowing elements from other namespaces to appear within WS-BPEL defined elements. This is allowed in the XML Schema specifications for WS-BPEL.
Extensions are either mandatory or optional (see section14). … In the case of mandatory extensions not supported by a WS-BPEL implementation, the process definition MUST be rejected. Optional extensions not supported by a WS-BPEL implementation MUST be ignored.
The first paragraph in the sample is descriptive and provides background information on how to extend the WS-BPEL language. It does not contain any RFC2119 keywords. The second paragraph contains Normative Statements that directs implementers and users what to do with unknown extensions, and uses the keywords to define what has to be done.
Normative statements form the core of a specification and it is essential that each statement be clear, concise, and unambiguous. It MUST be clear what Conformance Target the statement applies to, concise enough to be understood and what needs to be done SHOULD be clear.
It is recommended that the Conformance Targets be defined before Normative Statements are made in a specification,. From the above example, a WSPEL implementation is a Conformance Target. A specification may define one or more Conformance Targets as appropriate.
Normative statements MUST be referenceable so that a statement may be referenced from another part of a specification, but more importantly so they can be referenced from Conformance Clauses. Should the specification writer want fine grained referenceability, each Normative Statement SHOULD be uniquely labeled. This is the approach adopted by some organizations, such as WS-I. If the writer deems this to be too fine grained, then Normative Statements can appear in their own self-contained section, and the section referenced.
Where possible Normative Statements SHOULD not contradict each other, but there are times when this is unavoidable. In these cases, there MUST be a clear way to separate them so that implementers and users are not required to implement conflicting Normative Statements.
Examples of Normative Statements
The following example is taken from the Emergency management specification: http://docs.oasis-open.org/emergency/edxl-de/v1.0/EDXL-DE_Spec_v1.0.pdf
In the discussion on representing longitude and latitude the following Normative Statement is made:
Latitudes north of the equator MAY be specified by a plus sign (+), or by the absence of a minus sign (-), preceding the designating degrees. Latitudes south of the Equator MUST be designated by a minus sign (-) preceding the digits designating degrees. Latitudes on the Equator MUST be designated by a latitude value of 0.
This Normative Statement uses RFC2119 wording, it is clear what the subject is, and provides concise instructions. It is also self contained in that it does not introduce other concepts in the statement not related to latitude.
The following example is made up to protect the innocent and is an example of a badly written Normative Statement.
When processing a document some features can be ignored and not displayed.
First, the recommended keywords for a Normative Statement are not used; “can” needs to be replaced with MAY or MUST, and needs to be qualified. Second, it is not clear what features can be ignored; this would need to be qualified. Finally, a Conformance Target has not been defined, so it is not clear what processes a document. A better phrasing would be:
A word processor MAY ignore the following features contained within a document and SHALL choose NOT to display these features: …list of features.
A Conformance section of a specification must contain at least one Conformance Clause. A specification may define a number of different clauses in the Conformance section, where each clause identifies different Conformance Targets that SHOULD conform, such as an implementation, a document, an authoring tool, a protocol etc. Defining more that one Conformance Clause segments the specification into different targets for possible Conformance.
A Conformance Clause identifies that to which a Conformance Target MUST conform and this is done by reference to Normative Statements in the specification. A Conformance Clause therefore identifies a sub-set of the Normative Statements defined in the body of a specification. Thought should be put into the granularity of references to Normative Statements. If there are many Normative Statements referenced by a Conformance Clause then simply referencing each statement might not be readable or easy to follow. In such cases it may be better to revisit the Normative Statements and group them into larger referenceable units.
Conformance clauses MUST be defined within a separate Conformance section of an OASIS specification, and it is recommended that Conformance Clauses only appear in the Conformance section.
A specification MUST impose no restrictions about who can make a statement of use claiming Conformance to one or more Conformance Clauses (e.g., vendor, user, third party).
There MAY be more than one Conformance Clause in a specification, and like Normative Statements they MUST be clear, concise, and unambiguous.Each Conformance Clause MUST be uniquely labeled.
When more than one Conformance Clause exists in a specification the relationship between them MUST be clearly defined. To help the writer of Conformance Clauses, five types of relationships are defined below, and each provides a different means to relate one Conformance Clause to another one:
Combined – this defines a Conformance Clause that combines other clauses. For example, clause A, B, and C
Alternates – this defines a distinct Conformance Clause that exists on its own without reference to another one. For example, an implementer may implement clause A, B or C.
Level/extension – this defines a Conformance Clause by building on top of another one. For example, clause B requires A and extends with Normative Statements in addition to those defined by A.
Relaxation – this defines a Conformance Clause by removing some of the requirements of another Conformance Clause. For example, clause A but without Normative Statements x, y and z required by clause A.
It is possible to use a mixture of the above. For example, clause B extends clause A and requires clauses D or E. Care must be taken though not to over-complicate, so that each Conformance Clause is easy to understand and not open to different interpretations.
If any Conformance Clause references another one, it is essential that there be no contradictory Normative Statements within the clauses. If there is a contradiction, then the writers should either examine and try to remove the contradiction in the specification text itself or state in the Conformance Clause what must be done to avoid the contradiction, for example by stating that one overrides the other.
When multiple Conformance Clauses exist, it must be clear which are the top-level. It is these top-level clauses that relate to the Conformance Targets that users and vendors MUST conform to, and are the clauses that should be referenced when claiming Conformance to a specification and in making statements of use. For example, a specification may define 5 Conformance Clauses A, B, C, D and E, where D and E are referenced only by C; A, B and C are the top-level clauses in this case.
Within the Conformance section, a clear statement MUST be made as to how optional Normative Statements (i.e. those using the MAY keywords) must be handled. This decision relates to the type of Conformance Target and the use of the specifications. For example a document that claims Conformance to a schema does not have to use any optional features. However, in another scenario, a protocol target should implement optional features in case another party using the protocol makes use of the optional features. In deciding how to dispose of optional features, issues that effect interoperability and portability need to be considered.
Example
The following example is taken from ebXML Registry Services Specification v2.0, and illustrates how to write multiple Conformance Clauses and relate them to each other:
5.5 Implementation Conformance
An implementation is a conforming ebXML Registry if the implementation meets the conditions in Section 5.5.1. An implementation is a conforming ebXML Registry Client if the implementation meets the conditions in Section 5.5.2. An implementation is a conforming ebXML Registry and a conforming ebXML Registry Client if the implementation conforms to the conditions of Section 5.5.1 and Section 5.5.2. An implementation shall be a conforming ebXML Registry, a conforming ebXML Registry Client, or a conforming ebXML Registry and Registry Client.
5.5.1 Conformance as an ebXML Registry
An implementation conforms to this specification as an ebXML Registry if it meets the following conditions:
1. Conforms to the ebXML Registry Information Model [ebRIM].
2. Supports the syntax and semantics of the Registry Interfaces and
3. Supports the defined ebXML Registry Schema (Appendix B).
4. Optionally supports the syntax and semantics of Section 8.3, SQL
5.5.2 Conformance as an ebXML Registry Client
An implementation conforms to this specification, as an ebXML Registry if it meets the following conditions:
1. Supports the ebXML CPA and bootstrapping process.
2. Supports the syntax and the semantics of the Registry Client Interfaces.
3. Supports the defined ebXML Error Message DTD.
4. Supports the defined ebXML Registry Schema (Appendix B).
Section 5.5.1 is a Conformance Clause for an ebxml Registry Conformance Target. Section 5.5.2, is a Conformance Clause for an ebxml Registry Client. Both these clauses reference normative material. The introduction paragraph Section 5.5 defines three top level Conformance Clauses, references the clauses containing the details (5.5.1 and 5.5.2), and defines the relationship between the clauses. In this case it uses a mix of alternative and combined styles: an implementation is either a Registry, or a Client, or a Registry and a Client.