SpecLite Conformance Clause Template

Authors:
Lofton Henderson
Lynne Rosenthal
Date/version:
19 May 2004

Editors' Caveat: As explained in the @@Status@@ section of the @@companion Specification Guidelines@@ (SpecGL) document, SpecGL is being substantially revised (informal project name "SpecLite"). In response to feedback during CR publication and review period, it is being redesigned for simplicity, user-friendliness, and usability. A big part of that is providing tools and templates to facilitate and accelerate spec authors' work. This is an illustration of a major such tool/template -- the Conformance Clause Template. The present version should only be considered as an illustration, for the purposes of this publication. It was originally designed for the full content of CR SpecGL, and has not been fully coordinated with the reduced and simplified content of the redesigned, lightweight SpecGL.


Contents


About this template

The SpecGL collection

This 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 and good Conformance Clause is the probably the single biggest enabler of clear, testable specifications and interoperable implementations.

The other currently existing member of the collection is QA Framework: Specification Guidelines (SpecGL). SpecGL defines the normative set of rules for the topics of specification authoring, but does so as a set of helpful and non-authoritarian Principles and Good Practice advice. [TBD. The normativity of SpecGL's content is currently still under consideration and design.]

This template companion to SpecGL 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 SpecGL collection.

Satisfying SpecGL the easy way

This template is one easy way to satisfy the rules and guidelines of SpecGL. It is not the only way, and SpecLite users may implement other successful strategies of their own chosing. This template also contains markup of its sub-sections [TBD] -- use of it will enable the application of tools [TBD] provided by the QA Activity, that assist conformance verification and other useful tasks related to SpecGL.

[Ed note. Adding div/class markup to this template is yet tbd.]

Key to the template

SpecGL contains lots of examples. To improve its usability, this template contain a few links to examples from each one of the template sections. [Ed note. TBD. Is it going to contain example links? It would probably help user complete the template item.]

Legend:



[Ed note. This version of the CC 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. The ultimate form is yet TBD.]

Conformance Clause for FooML

"All important information about conformance to FooML can be found starting here in this Conformance Clause."

[Having a Conformance Clause like this satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Finding FooML's normative content

Normative & Informative parts

"The normative parts of this specification are identified by:" [Note to template user: here you should described how normative bits are distinguished from informative bits in the specification: choice of { markup | section labelling | enumeration here | other (specify) }.

[Distinguishing normative/informative content satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]

Normative language

"The language and method of expression used for individual conformance requirements or testable statements in this specification is:" [Ed note. TBD update the following...]

[Defining the language/style/markup for testable requirements satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]

FooML's Conformance model

"The conformance model of FooML is defined collectively by:

FooML defines conformance for...

[Note to template user: 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.]

[Ed note. Might (or might not) want to get rid of CoP terminology and replace it w/ something more common. But it is a convenient handle for now.]

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

[Note to template user: Include such a subsection for each Class of Product.]

[Identifying things for which FooML defines conformance satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]

Conformance designations

[Ed note. We have something here that we believe (according to discussions during SpecGL TAs) is worthwhile, but we have had a bit of trouble nailing it down. It subsumes the following two bits from old SpecGL and the associated checkpoints.

"This specification uses these conformance concepts:" [explain/instruct template user to complete this section, referencing common conformance concepts from SpecGL or other literature, and defining any new concepts that may be invented and used in the specification.] [Satisfies CP8.2]

"The conformance designations used by this specification are:" [explain/instruct template user to complete this section, referencing common conformance concepts from SpecGL or other literature, and defining any new concepts that may be invented and used in the specification.] [Satisfies CP8.5]

]

[Identifying ...<this>...satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1 WCAG10 A/AA/AAA@@; @@Example 2 SVG static/dynamic(?)@@; @@Example 3@@]

Ways that conforming FooML implementations may differ

Profiles

"FooML {does | doesn't } address and define profiles to subdivide the technology."

[Note to template user: 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]

"FooML {does | doesn't } address and define rules for profiles, which establish FooML's definition of what comprises a valid profile."

[Note to template user: If "doesn't, this section is optional. If "does", then describe the scheme, subdivisions, targetted application sectors, any constraints, etc.]

[Identifying FooML's use of profiles satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]

Modules

"FooML {does | doesn't } address and define modules to subdivide the technology."

[Note to template user: 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.]

[Identifying FooML's use of modules satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]

Levels

"FooML {does | doesn't } address and define levels to subdivide the technology."

[Note to template user: 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.]

[Identifying FooML's use of levels satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]

Deprecated features

"FooML {does | doesn't } deprecate features from previous version(s)."

[Note to template user: 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 affectedCoP.]

[Identifying and describing any deprecation in FooML satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1 MathML@@; @@Example 2)@@; @@Example 3@@]

Obsolete features

[Ed note. Haven't decided whether or not to have this at all, fold it into previous at GL/CP level, fold it in at template level, fold it in at the ET level, etc.]

Discretionary items

"FooML {does | doesn't } allow any discretionary items."

[Note to template user: 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 @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]

Extensibility

"FooML { is | is not} extensible".

[Note to template user: If "is", then complete the following:

]

[Identifying and describing extensibility policy in FooML satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]

Conformance claims

[Ed note. Undecided whether to include the ICS pro-forma stuff here, there, neither, optional etc. I think "not" for GL/CP, but maybe bring it up in SpecET as a good supplemental thing to do.]

[Addressing FooML's conformance claim policy satisfies @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]