WARNING: This document is being edited. It's a draft.
This template is one of a collection of documents about how to make specifications clearer, more precise, and more testable. It provides a template for authors to use in constructing Conformance Clause sections for their specifications. Clear conformance specifications in a good Conformance Clause is probably the single biggest enabler of clear, testable specifications and interoperable implementations.
Specification Guidelines defines both a normative set of rules and recommended practices about specification authoring, in the form of helpful and non-authoritarian Principles and Good Practice advice. This template companion to Specification Guidelines is defined so that specification authors should be able to start in either document and find most of the useful advice and benefit of the Specification Guidelines collection.
This template is one easy way to satisfy the rules and guidelines of Specification Guidelines. It is not the only way, and Specification Guidelines users may implement other successful strategies of their own chosing. This template also contains markup of its sub-sections — use of it will enable the application of tools provided by the QA Activity, that assist conformance verification and other useful tasks related to Specification Guidelines.
Specification Guidelines contains lots of examples. To improve its usability, this template contain a few links to examples from each one of the template sections.
Template
This section contains the text of the template that you can copy and paste in your own conformance section. Some of these sections contains multiple choices that you have to select.
Instructions
In the section Instructions you will find the information necessary to the completion of the template.
The tip is a reference to the Good Practice and/or Requirements that you will meet by following this section of the conformance clause template.
The example section gives links to the different examples given in the Specification Guidelines.
This version of the Conformance Clause Template is written in the manner of a "virtual conformance clause", about a fictitious FooML, rather than classical "template" style. This is done for illustration purposes.
Template
All important information about conformance to FooML can be found starting here in this Conformance Clause.
Instructions
Having a Conformance Clause like this satisfies Requirement 01
Ruby Annotation [RUBY] specification is an example of a short specification with a detailed conformance clause.
SVG 1.0 [SVG11] specification contains a detailed conformance clause for a complex modular technology.
Template
The normative parts of this specification are identified by:
Instructions
Here you should described how normative bits are distinguished from informative bits in the specification, choose one or more of
Distinguishing normative/informative content satisfies Good Practice 02
XHTML 1.0 [XHTML10] uses the words of RFC2119 but in an extended way (See Definitions [XHTML10]). The specification defines each word.
Template
Instructions
The language and method of expression used for individual conformance requirements or testable statements in this specification is using RFC2119. The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are used as defined in RFC 2119 [RFC2119].
Mention any distinguishing styling like bold, upper case, or specific markup, etc.
The imperative style uses the imperative form to convey the requirement; guidelines or specifications that need the reader's involvement often use it.
The descriptive style takes a different approach. It describes the semantics of the language, rather than how it must be handled.
if RFC2119 is not used, here also you should address the “mandatoriness” of conformance requirements, e.g., whether they are mandatory, recommended, or optional.
Tips: Defining the language/style/markup and "manditoriness" for testable requirements satisfies Requirement 7, Requirement 8
In the SVG 1.1 [SVG11] Recommendation, the semantics are defined in descriptive style, and the implementation requirements are defined in RFC 2119 key words in the SVG 1.1 Conformance section.
For instance, HTTP 1.1 [HTTP11] defines two types of conformance, one where all the MUST are respected, and one where all the MUST and the SHOULD are implemented.
Template
The conformance model of FooML is defined collectively by:
Instructions
To clearly identify the conformance model, address these points
Addressing these aspects in a conformance model section satisfies Good Practice 1
XML 1.0 [XML10] has two classes of products (document and processor). Each of those has two conformance degrees (well-formed/valid and validating/non-validating). xml:base, XML Namespaces and XLink could also be considered as “modules” for XML even though they have not been formally defined as such.
SVG 1.1 [SVG11] has roughly four classes of products (markup fragments with various extents, generators, interpreters and viewers). Some of these classes of products have various degrees of conformance (Appendix G: Conformance Criteria [SVG11]), e.g., static / dynamic for interpreters and static / dynamic for high-quality for viewers. SVG 1.1 also defines modules that are grouped into profiles (tiny/mobile/full).
Template
Instructions
each group of similar things that may conform is known as a Class of Product — things like FooML instances, FooML generators, FooML parsers, FooML interpreters, etc., each are a Class of Product.
Template
This FooML specification defines conformance for:
Each of the following subsections discusses and defines one of the CoP of FooML in more detail. In particular, they give the high-level view of the criteria for conformance to each CoP of FooML.
Instructions
Include such a subsection for each Class of Product.
Identifying things for which FooML defines conformance satisfies Requirement 3
Mathematical Markup Language (MathML) Version 2.0 (Second Edition) [MATHML20] defines output-compliant authoring tools and input-compliant rendering/reading tools.
SMIL 2.0 Language Profile ([SMIL20], chapter 13) has two classes of products: documents and basic user agents.
The conformance section of Ruby [RUBY] is very explicit and detailed about classes of products. For each of these classes, the Ruby conformance section defines a set of rules the implementers must respect. Ruby defines rules for markup, DTD, document, module, generator, and interpreter.
Template
This specification uses these conformance designations:
Instructions
Complete this section, referencing common conformance concepts from Specification Guidelines or other literature, and defining any new concepts that may be invented and used in the specification.
Template
The conformance labels used by this specification are:
Instructions
Complete this section, as explained in Requirement 6 of Specification Guidelines, defining any new concepts that may be invented and used.
Identifying conformance designations satisfies Good Practice 1, and conformance labels satisfies Requirement 6
XML 1.0 [XML10] has two classes of products (document and processor). Each of those has two conformance degrees (well-formed/valid and validating/non-validating). xml:base, XML Namespaces and XLink could also be considered as “modules” for XML even though they have not been formally defined as such.
SVG 1.1 [SVG11] has roughly four classes of products (markup fragments with various extents, generators, interpreters and viewers). Some of these classes of products have various degrees of conformance (Appendix G: Conformance Criteria [SVG11]), e.g., static / dynamic for interpreters and static / dynamic for high-quality for viewers. SVG 1.1 also defines modules that are grouped into profiles (tiny/mobile/full).
XML 1.0 [XML10] defines a well-formed XML document, a valid XML document.
WCAG 1.0 [WCAG10] defines a level A conformant document.
SVG 1.1 [SVG11] defines “conforming SVG document fragments,” “conforming interpreters,” “conforming viewers.”
Template
FooML explicitly allows conforming implementations to vary in these ways …
Instructions
choice list, select a subset of: Profiles, Modules, Levels, Deprecated Features, Discretionary Items, Extensibility.
Instructions
If "doesn't", this section is optional, but it doesn't hurt to be explicit about it.
If "does", then describe the scheme, subdivisions, targetted application sectors, any constraints, etc. of any profiles defined by FooML
Addressing these aspects of FooML's use of profiles satisfies Good Practice 13, Requirement 9, Requirement 10
Profile: XHTML Modularization [XHTML-MOD] in section 3 and Synchronized Multimedia Integration Language (SMIL 2.0) Specification [SMIL20] define rules for profiles.
Synchronized Multimedia Integration Language (SMIL 2.0) Specification [SMIL20] has a SMIL 2.0 Language Profile for user agents (see section 13 [SMIL20]) but also provides a SMIL 2.0 Basic Profile for wireless and embedded devices (see section 14.3 in [SMIL20]). The SMIL 2.0 Language Profile requires that a user agent implement the BasicAnimation module but not the SplineAnimation module. The SMIL 2.0 Basic Profile on the other hand does not require implementation of any of the animation modules.
Template
FooML {does | doesn't } address and define rules for profiles, which establish FooML's definition of what comprises a valid profile.
Instructions
If "doesn't", this section is optional.
If "does", then describe the scheme, subdivisions, targetted application sectors, any constraints, etc.
Addressing whether FooML defines rules for satisfies Good Practice 14
WebCGM 1.0 [WEBCGM10] defines rules to create Profiles (see section 1.2 in [WEBCGM10]).
Instructions
If "doesn't, this section is optional, but it doesn't hurt to be explicit about it.
If "does", then describe the scheme, enumerate the subdivisions, targetted application sectors, any constraints, etc.
Addressing these aspects of FooML's use of modules satisfies Good Practice 13, Requirement 9, Requirement 10.
Modules: XHTML Modularization [XHTML-MOD] and Synchronized Multimedia Integration Language (SMIL 2.0) Specification [SMIL20] give good examples of modules usage.
XHTML Modularization [XHTML-MOD] defines minimal requirements for including certain basic modules when designing an XHTML Modularization-conformant document.
Instructions
If "doesn't", this section is optional, but it doesn't hurt to be explicit about it.
If "does", then describe the scheme, enumerate subdivisions, targetted application sectors, any constraints, etc.
Addressing these aspects of FooML's use of levels satisfies Good Practice 13, Requirement 9, Requirement 10.
In CSS and DOM, levels are the result of progressive historical development and technology enrichment realized in a series of specifications.
Profile/Level combination: Mobile SVG Profile: SVG Tiny, Version 1.2 [SVG-MOBILE] define three profiles - Tiny, Basic and Full - which are nested, like levels, each targeted at specific hardware communities.
Instructions
If "doesn't, this section is optional, but it doesn't hurt to be explicit about it.
If "does", then list & describe, or provide links to, all of the deprecated features of the specification. Here or at linked locations, describe the conformance requirements each deprecated item for each affected CoP.
Identifying and describing here, or here linking to, these aspects of any deprecation in FooML satisfies Requirement 12, Requirement 13, Good Practice 21
HTML 4.01 [HTML401]: The specification has a full list of elements and attributes. The deprecation status appears in both lists. There is an entry in the table of contents to these two lists. Each element and attribute has a link to its definition in the specification.
In Mathematical Markup Language (MathML) Version 2.0 (Second Edition) [MATHML20], MathML2.0 section 7.2.1.2 describes deprecated MathML 1.x features in terms of MathML-output-conformant authoring tools, MathML-input-conformant rendering/reading tools, and MathML-roundtrip-conformant processors.
The conformance section of HTML 4.01 [HTML401] defines deprecation and what user agents should do. The behavior for other kinds of products is undefined.
The Namespaces XML 1.1 [NAMESPACES11] deprecation of IRI references includes a link to the deprecation ballot results, providing background information on the proposal to deprecate, what the deprecation means with respect to conformance to XML 1.0 and namespaces as well as its effect on other specifications (i.e., DOM, XPath).
HTML 4.01 [HTML401] gives numerous examples on how to avoid the markup that was used in previous versions for deprecated elements.
Template
FooML {has | hasn't } made features from previous version(s) obsolete.
Instructions
If "doesn't, this section is optional, but it doesn't hurt to be explicit about it.
If "has", then list & describe all of the obsolete features of the specification.
Identifying any obsolete features of FooML satisfies Good Practice 22
The HTML 4.01 [HTML401] specification has a full list of elements and attributes. The obsolete status appears in both lists. There is an entry in the table of contents to these two lists. Each element and attribute has a link to its definition in the specification.
HTML 4.01, Appendix A: Changes lists obsolete elements and suggests an alternative element for use. The following elements are obsolete:
LISTING, PLAINTEXT, and XMP. For all of them, authors should use the PRE element instead.
Instructions
If "doesn't, this section is optional, but it doesn't hurt to be explicit about it.
If "does", then list & describe, or provide links to, all of the discretionary items of the specification.
Identifying and describing discretionary items in FooML satisfies Good Practice 15, Good Practice 16, Good Practice 17
Template
FooML {is | is not} extensible.
Instructions
Stating FooML's extensibility policy satisfies Requirement 11.
If "is", then complete the following:
Template
Instructions
It's very important. Just do it.
Addressing these aspects of FooML's extensibility policy satisfies Good Practice 19, Good Practice 18
The specification CSS3 module: Syntax [CSS3-SYNTAX] has addressed the topic of extensions for CSS 3. The specification clearly identifies extensibility in the table of contents and there is a specific section for it.
Template
Instructions
Completing the above information in FooML's conformance clause satisfies Good Practice 3
WCAG 1.0 [WCAG10] is a good example of a specification explaining how to make a conformance claim depending on the degree of conformance.
Specification Guidelines section 4.4 Conformance Claims provides this document's template for conformance claims.
Template
Instructions
Choice-of-two, you should complete one of the previous statement.
Providing a FooML ICS pro-forma satisfies Good Practice 4, and requiring its usage in conformance claims satisfies Good Practice 5
QA Specification Guidelines provides an ICS [QA-SPEC-ICS] to help implementers to asses conformance to this document. Good Practices (informative) and Requirements (normative) are given in a table where implementers can check “Yes,” “No,” or “Not Applicable” and add comments.
Web Content Accessibility Guidelines 1.0 [WCAG10] provides a checklist of checkpoints which helps the implementer to verify the accessibility of HTML documents.
The WebCGM specification requires an ICS as part of a conformance claim. The WebCGM checklist describes the conformance of the subject viewer product to the WebCGM specification, according to its performance on the WebCGM Test Suite.