- Author:
- Lofton Henderson
- Date/version:
- 31 January 2004
Contents
This document contains an outline of the recommended Conformance
Clause template. It is a supplement to the main templates report.
The CC template will assist the implementation of 31 of the 46 checkpoints
of SpecGL (enumerated in the
main templates report). Note that some of the supported checkpoints are "in
limbo" (deferred), as explained
in the main report, because of substative issues in SpecGL.
The outline is presented from the perspective of directives to the author
of the template, i.e., the person who eventually takes the outline to a full,
usable template.
All CP designations in the template (e.g. "CP2.1") should link back to the
appropriate checkpoint in the CR SpecGL specification. See QAPD
template for example of how this might be done.
Some of the template entries will be almost complete the implementation of
the checkpoint. Some will be little more than an instruction to the template
user to "do it here". In the template itself, we should identify the "do it
here" cases, and proved links to Quick Tips to help template users to finish
the template item. (I.e., the QTs are really individual-CP templates, which
will be invoked from here, the skeleton conformance clause.)
Legend:
- [Satisfies CPx.y] -- suggest to include this in the template, w/ link
from CPx.y to that CP of SpecGL.
- [...] -- other stuff in square brackets are directed at the author of
this template, i.e., the person who takes the outline to a full template.
They are suggestions about what to include at that point in the
template.
- "..." -- prototype wording which might be included directly in the
template.
- bullet lists -- bullet lists within subsections are mostly for
organization purposes of this outline. They are not necessarily implied
to be part of the template produced from this outline, or a CC produced
from the template by the template user.
- section headings -- these are, verbatim, the suggested headings for the
template, and for user's Conformance Clause that results from using the
template
The outline follows:
[Satisfies CP8.4]
Finding key conformance information
"All key conformance-related information for this specification may be
found by starting in this conformance clause." [instruct template user to
ensure that this CC is linked from the specification's main TOC, and also to
(recommended) include a detailed sub-section TOC right here]. [Satisfies
CP7.4]
Normativity
Normative & Informative parts
"The normative parts of this specification are:" [instruct template user
to described how normative from informative bits are identified in the rest
of the specification; choice of { markup | section labelling | enumeration
here | other (specify) }. [Partially satisfies CP7.2].
Normative language
"The language and method of expression used for individual conformance
requirements or testable statements in this specification is:" [instruct the
user to choose:
- either RFC2119
- include normal boiler plate
- or "other"
- describe the method;
- explain why RFC2119 keywords are not used. ]
[Satisfies CP7.1]
Conformance concepts used in this specification
"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]
Classes of product
- "This specification defines conformance for:" [include choice list per
SpecGL sec2.3 for template user, and explanation/instructions to chose
the appropriate item(s), or define their own if no items fits].
[Satisfies CP2.1.]
- "The conformance criteria for each class of product are:" [tell
template user to define what they are here, in tables or subsections or
bullet lists or ...]. [Satisfies CP2.2] [Ed note. These conformance
criteria are collective and at a higher level that the enumeration of
individual atomic ConfReqs or TAs]
- "The following requirements
- [if there is more than one CoP, this item must be included] "This
specification's CoPs interact with the other DoV it uses as follows:"
[explain/instruct the user to address limitations, constraints,
interactions, etc]
Alternative to last bullet:
- include a single subsection in the CC which addresses all of these
similar DoV-interrelationship CPs at once, in prose, tables, or whatever:
CP2.4, CP3.5, CP 4.3, CP5.5, CP6.6
Dimensions of variability
[explain/instruct template user to complete this section, enumerating the
appropriate DoV; else stating that the conformance definitions are monolithic
and have no variability]
- "Conforming implementations to this specification may legitimately vary
in these ways: [choice list including: CoP, Profiles, Modules, Levels,
Deprecated Features, Discretionary Items, Extensibility.] [Satisfies part
of CP7.4]
- [explain/instruct to the template user that, if any DoV are enumerated,
to justify the usage of each such DoV by the specification.] [Satisfies
CP8.3].
Profiles
[explain/instruct to the template user that this section should included
if profiles are one of the DoV enumerated in the above DoV
subsection; it is optional otherwise (a negative disclaimer that
profiles are not defined or addressed in this specification).]
[If this section is purely a negative disclaimer about profiles, instruct
to stop here. Else, explain/instruct the user to finish these items:]
- [explain/instruct to the template user to address: is the concept of
conformance restricted to profiles? or does the specification define
conformance also independently of conformance to a profile?] [Satisfies
1st part of CP3.1]
- [...I don't understand the 2nd part of CP3.1...]. [Satisfies 2nd part
of CP3.1]
- [Address CP3.2 here, "minimal requirements"]. [...issue that SpecGL is
unclear and possibly wrong in ConfReqs of CP3.2]. [Satisfies CP3.2]
- [explain/instruct the template user to define whether the specification
addresses rules about and validity of user-defined profiles]. [Satisfies
CP3.3]
- "This specification's profiles interact with the other DoV it
uses as follows:" [explain/instruct the user to address limitations,
constraints, interactions, etc]. [Partially satisfies CP3.5].
Alternative to last bullet:
- include a single subsection in the CC which addresses all of these
similar DoV-interrelationship CPs at once, in prose, tables, or whatever:
CP2.4, CP3.5, CP 4.3, CP5.5, CP6.6
Modules
[explain/instruct to the template user that this section should be here if
modules are one of the DoV enumerated in the above DoV subsection;
it is optional otherwise (a negative disclaimer that modules are not
a factor in this specification).]
- [explain/instruct to the template user to address: any mandatory
conditions or constraints on the usage of modules, and present the bullet
list of CP3.4 as choices, adding "* other (explain)" at the end]
[Satisfies CP3.4]
- "The definition and usage of modules in this specification interact
with the other DoV it uses as follows:" [explain/instruct the user to
address limitations, constraints, interactions, etc]. [Partially
satisfies CP3.5].
Alternative to last bullet:
- include a single subsection in the CC which addresses all of these
similar DoV-interrelationship CPs at once, in prose, tables, or whatever:
CP2.4, CP3.5, CP 4.3, CP5.5, CP6.6
Levels
[explain/instruct to the template user that this section should be here if
levels are one of the DoV enumerated in the above DoV subsection; it
is optional otherwise (a negative disclaimer that levels are not a
factor in this specification).]
- "This specification's levels interact with the other DoV it
uses as follows:" [explain/instruct the user to address limitations,
constraints, interactions, etc]. [Partially satisfies CP3.5].
Alternative to that:
- include a single subsection in the CC which addresses all of these
similar DoV-interrelationship CPs at once, in prose, tables, or whatever:
CP2.4, CP3.5, CP 4.3, CP5.5, CP6.6
Deprecated features
[explain/instruct to the template user that this section should be here if
the specification contains any deprecated features; it is optional otherwise
(a negative disclaimer that there are no deprecated features in this
specification).]
- [explain/instruct to the template user to enumerate here all deprecated
features in the specification; the enumeration can be full description
here, or a table/list of links to specific parts of the specification's
text] [Satisfies CP4.1]
- [explain/instruct to the termplate user: for each deprecated feature,
specify the conformance implications for each Class of Product; can
either be done here, or at destination text locations if table/list of
links was used to satisfy CP4.1]. [Satisfies CP4.2]
- "The deprecated features in this specification interact with the other
DoV it uses as follows:" [explain/instruct the user to address
limitations, constraints, interactions, etc]. [Satisfies CP4.3].
Alternative to last bullet:
- include a single subsection in the CC which addresses all of these
similar DoV-interrelationship CPs at once, in prose, tables, or whatever:
CP2.4, CP3.5, CP 4.3, CP5.5, CP6.6
Obsolete features
[explain/instruct to the template user that this section should be here if
the specification obsoletes any features of previous versions; it is optional
otherwise (a negative disclaimer that no features of previous versions are
obsoleted by this specification).]
- [explain/instruct to the template user enumerate here all deprecated
features in the specification; the enumeration can be full description
here, or a table/list of links to specific parts of the specification's
text] [Satisfies CP4.6]
Discretionary items
[Editor note. All CPs of GL5 are "deferred", until ambiguities of meaning
and conformance requirements are resolved in SpecGL. That said, CP5.1 is
probably clear enough to implement in the template now, in the style of
CP4.1's implementation above.]
Extensibility
"This specification [instruct template user to make choice of: is; is not]
extensible". [Satisfies CP6.1 (part)]
[Indicate to the template user that the remainder of this section must be
completed if "is extensible" applies; the items may either be included here
in-line in this CC subsection, or in an external chapter that is linked from
here]
- [Instruct template user to address the remaining bullets in CP6.1 of
SpecGL]. [Satisfies CP6.1 (rest)]
- [Instruct template user to include a statement such as...] "The valid
use of extensions as permitted and described by this specification shall
not negate or contradict standardized, defined functionality of this
specification." [Satisfies CP6.2]
- [Instruct template user to define a standardized mechanism and syntax
by which a statement by which extensions are expressed, invoked, etc].
[Satisfies CP6.3].
- [Instruct template user to include a statement such as...] "If an
implementation (instance) of a CoP implements extensions as permitted and
described by this specification, then that implementation must have
associated publicly available documentation of the extensions, in order
for that invocation of extensibility to be considered valid according to
this specification.." [Satisfies CP6.4]
- [Instruct template user to explain whether or not the specification
requires -- accompanying valid invocations of extensibility -- features,
alternatives, etc that mitigate the interoperability impacts of the
extensions.] [Satisfies CP6.5]
- "The extensibility permitted by this specification interacts with the
other DoV it uses as follows:" [explain/instruct the user to address
limitations, constraints, interactions, etc]. [Satisfies CP6.6].
Alternative to last bullet:
- include a single subsection in the CC which addresses all of these
similar DoV-interrelationship CPs at once, in prose, tables, or whatever:
CP2.4, CP3.5, CP 4.3, CP5.5, CP6.6
Conformance claims
This report was prepared with the support of National Institute of
Standards and Technology, Gaithersburg, MD 20899-8970.