Abstract
A lot of effort goes into writing a good specification. It takes more than knowledge of the technology to make a specification precise, implementable and testable. It takes planning, organization, and foresight about the technology and how it will be implemented and used. The goal of this document is to help W3C editors write better specifications, by making a specification easier to interpret without ambiguity and clearer as to what is required in order to conform. It focuses on how to define and specify conformance for a specification. Additionally, it addresses how a specification might allow variation among conforming implementations. The document is presented as a set of guidelines or requirements, supplemented with good practices, examples, and techniques.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is the 22 November 2004 Last Call Working Draft (WD) of “QA Framework: Specification Guidelines”, made available by the the QA Working Group of the W3C Quality Assurance (QA) Activity for discussion by W3C members and other interested parties. For more information about the QA Activity, please see the QA Activity statement.
This is the Last Call, third published version of this document after the decision to completely redesign the QA Framework, resolved by the QA Working Group at its 2004 Technical Plenary face-to-face. It is a lighter-weight, less authoritarian, more user-friendly and useful version of the previously published Candidate Recommendation version of the QA Specification Guidelines.The changes since the previous version are documented in the changelog and highlighted in a separate document.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Patent disclosures relevant to this specification may be found on the Working Group's Patent disclosure page in conformance with the W3C Patent
Policy of 5 February 2004. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.
The Working Group expects this specification to become a Recommendation. The Last Call review period ends 28 January 2005, at 23:59 EDT. Please
send Last Call review comments on this document before that date to www-qa@w3.org, the publicly archived list of the QA Interest Group. Reviewers please note that your comments will be publicly archived and available; do not send information that should not be distributed, such as private data.
Last Call Working Draft status is described in
section 7.4.2 of the W3C Process Document. To the extent possible, please provide a separate email message for each distinct comment.
Table of contents
Appendix
Introduction
Scope
This document is a guide for W3C specifications editors and authors. It provides guidelines for writing better specifications. This document differs from other W3C process and publication related documents in that it looks at specifications from a conformance viewpoint. It address the most basic and critical topics with respect to conformance, including how to convey what is required for an implementation in order to conform and how to allow variation among conforming implementations.
What is a specification?
A specification is a set of technical requirements which aim at defining a reliable interface to accomplish a given task.
Specifications can be defined in one or several documents, and can import requirements of other specifications with normative references. Some specifications, denoted below as umbrella specifications, create their own interfaces by simply grouping requirements of existing specifications in a well-defined manner.
Goals and Motivation
The goal is to enable Working Groups to produce specifications that are precise, easier to interpret without ambiguity or confusion, and clearer as to what is required in order to conform. Good specifications lead to better and more interoperable implementations and foster the development of test suites and tools.
Everyone benefits from having well-written specifications. Editors may have less rework and thus, fewer issues raised during the development of the specification, and fewer errata once it is finished. Implementers can implement sooner and have a better chance to conform to the specification. Test developers are able to derive unambiguous test assertions. Users benefit by having interoperable solutions. W3C gains by having recommendations produced with higher quality and reduced maintenance.
Why Specification Guidelines?
It is not an easy task to write accurate, clear, complete, unbiased specifications. It requires planning, organization, and foresight about the technology, how it will be implemented and used, and how technical decisions affect conformance. This document provides a collection of requirements, good practices, examples, and techniques that leads the reader through the decisions that need to be made in order to write precise requirements and establish, define, and specify conformance for specifications. Realizing that editors and authors are busy, under pressure to get the specification published, and already have a reading list of W3C documents (a good place to start, W3C Editor's Home Page [EDITOR]) this document can be used as a checklist of things to consider, a how-to guide with examples and techniques which can be adapted, and a reference for understanding conformance concepts and terminology.
Audience of this document
The primary audience of this document is editors and authors, however, it is applicable to a broader audience including:
- those who review specifications during their development
- implementers of specifications
- builders of test materials, including conformance test suites and tools.
This document makes no distinction between the terms editors and authors and refers to them collectively as editors.
About this document
This document is a practical guide to writing a specification, presenting editors with topics to consider. Consequently, much of the document is non-normative recommendations labeled Good Practices. There are however, a limited number of normative requirements, labeled Requirements, that must be implemented in order to conform to this document. The overall objective of these requirements and good practices is to facilitate the creation of a complete conformance clause in every specification. A conformance clause template [CONF-TEMPLATE] is provided to assist editors satisfy the requirements of this document and end up with a conformance clause. Note that for some specifications (e.g., The QA Handbook [QA-HANDBOOK], Architecture of the World Wide Web, First Edition [WEB-ARCH]) where conformance is not an issue (e.g., no normative content), the conformance clause may be an explanation of why there is no "conformance to this document" and may be presented in another section rather than in a separate conformance section.
The topics presented are herein inclusive (self-contained) providing information needed to understand and successfully apply the requirement, although related information and advanced topics may be referenced.
If in a hurry just read the first section, Specifying conformance
— this may be all you need to read in order to reach the expected outcome of adhering to this document, i.e. specificying conformance. It serves as a roadmap to other parts of this document, which help achieve specifying conformance.
Structure of this document
This document is organized into a series of main topics such as Specifying Conformance and Managing Variability. In each of these topic areas, Requirements and Good Practices are presented and explained. Each Requirement and Good Practice is accompanied by techniques and examples. The techniques illustrate basic (and non exhaustive) questions or methods to help realize the Requirement/Good Practice and write bits of the specification. The examples are explanations or extractions from existing W3C specifications which specifically illustrate the point made in the Requirement/Good Practice.
The conformance requirements of this document are described in the conformance section of this document. A specification editor who wishes to conform to Specification Guidelines must satisfy the conformance requirements in the conformance section of this document. It basically defines the requirements as normative and the good practices as informative.
This document can be used as a stand alone document or as part of a family of QA Framework documents designed to help the Working Groups improve all aspects of their quality practices.
- The QA Handbook [QA-HANDBOOK] is a non-normative handbook about the process and operational aspects of the quality practices of W3C Working Groups.
- Variability in Specifications, which models how design decisions affecting conformance change the interoperability landscape for a specification
- various in progress pages in the QA Wiki on developing a test suite
Guidelines
Clear presentation of what is meant by conformance to the specification is crucial to successful interoperability of implementations. The conformance model, its description and the language used to convey normative information not only determines the testability of a specification, but also influences the overall implementation landscape e.g., multiple types of conformance resulting in numerous, fragmented, conforming implementations or a limited type of conformance resulting in few allowable variations among implementations.
Conformance is the fulfillment of a product, process, or service of specified requirements. These requirements are detailed in a specification as part of a conformance clause and in the body of the specification. A conformance clause is a section of a specification that states all the criteria that must be satisfied in order to claim conformance to the specification.
A good conformance clause is the ultimate goal of these guidelines, and is sanctioned by conformance to this specification
The conformance clause of a specification is a high-level description of what is required of implementations. It, in turn, refers to other parts of the specification for details. Ideally, it is the root source from which readers can find any conformance-related information.
For some specifications, the conformance model may be straightforward and simple, and the conformance clause template [CONF-TEMPLATE] when completed, may provide most of the information needed in a conformance clause. For others, the conformance model is complex or convoluted, and the Advanced Topics
references may be invaluable in creating the conformance clause.
The central message of this section — “have a good conformance clause” —has many ancillary details. Because the conformance clause is the foundation for defining and measuring conformance, it is also the basis for assessing conformance claims. One detail worthy of attention is “valid conformance claims”.
Rather than live with the infinite varieties of creative conformance claims that can arise in a vacuum, the specification can be proactive.
1.2 Good Practice B:
Provide an Implementation Conformance Statement proforma.
What does it mean? An Implementation Conformance Statement (ICS) provides standardized information about the conformance of an implementation to the specification. It is used to indicate which capabillities and optional features have been implemented, as well as the limitations of the implementation. An ICS typically takes the form of a questionnaire for implementer to complete.
This Good Practice suggests that the specification itself include an ICS proforma.
Why care? An ICS provides a concise view of a specification’s conformance model. View the ICS as a template, where
its organization, format and content can provide implementers and users a
quick overview of the specification's features, subdivisions of
the technology, conformance requirements, etc. It can be especially
valuable as a statement of conformance, where implementers indicate which
mandatory and optional features they implement and document the presence of
extensions. Once completed by an implementer it can be used as part of the
conformance claim. Additionally, an ICS can be used to identify the subset
of a test suite that would be applicable to the implementation to be tested: this is useful first when establishing an interoperability report, and then when setting up a conformance testing program.
Techniques
- Create a list, table or form listing all features (capabilities) and indicating if it is mandatory or not.
- Provide space for the implementer to check: Yes, No, Not Applicable
- Organize the features according to the subdivisions of the specification or in the order they occur in the specification or in some other logical grouping
- If there are dependencies, express them. (For instance, if No to this question, jump to the next section.)
- Provide a tool to help implementers fill out the ICS and produce a report (e.g., EARL).
Examples
QA Specification Guidelines provides an ICS [QA-SPEC-ICS] to help implementers to verify the conformance to this document. Good practices (informative) and Requirements (normative), organized following the sections of the document, are given in a table where implementers can check yes, no or not applicable.
1.2 Good Practice C:
Require an Implementation Conformance Statement as part of valid conformance claims.
What does it mean? This simply puts together the previous two good practices. Not only could the specification provide an ICS proforma for implementers, but it could require it to be linked from its standardized conformance claim template.
Why care? Providing a filled ICS with the conformance claim might help customers and users to verify easily the level of support of individual requirements of the specifications. It also strengthens the value of the claim.
Techniques
- Give precise instruction how the ICS must be part of the conformance claim. It might be an external document, a link to precise dated document, etc.
2. Setting up Groundrules
2.1. Scope
The path to a quality specification begins with its scope. It is critical to convey what the specification is about by describing its intent and applicability. As the specification develops, it is a good idea to revisit the scope to make sure it still reflects the intent of the specification or if it needs to be modified.
2.1 Requirement A: Define the scope.
What does it mean?
Describe what the specification is about. Let the reader know what is covered in the specification.
Why care?
This is one of the first sections a reader reads, so it is important to capture their attention and make sure they understand what the specification is about. It helps to keep the specification content focused. It also help readers know the limits or boundaries of the specification and whether it is of interest to them.
Techniques
- Make the scope easy to find.
- Include the scope section in the beginning of the document
- Make “Scope” an item in the table of content
- Write simple, direct statements of fact. Don’t include any requirements in the scope section. Use statements such as: This document
- — specifies a method of …
- — specifies the characteristics of …
- — defines…
- — establishes a system for …
- — establishes general principles for …
- — is a guide for …
- In addition to describing the subject of the specification, address the following to achieve a more complete scope:
- Applicability of the specification,
- Purpose, objectives, and goals,
- Types of products or services (i.e., classes of products) to which the specification applies,
- Relationship to other specifications or technologies,
- What is not in scope, i.e., what the specification is not about,
- Limitations on the application of the specification.
Note that it is not necessary to write a separate statement for each of these items, rather, they can be combined.
Examples
Many W3C specifications have included a scope prose in the Abstract section. We advocate making the scope a separate section in the body of the specification, making it easy to find and insuring that it is an item in the table of contents.
2.1 Good Practice B:
Provide examples, use cases, and graphics.
What does it mean?
Illustrate concepts, behaviors, functionality, interaction, etc. through what ever means makes sense, such as examples, use cases, graphics, and sample code. This aids in the understanding of the specification, especially for areas that are innately complex or for which the Working Group has had to explain to its members or the public. Additionally, a set of broad examples and use cases can help to clarify the specification’s scope.
Why care?
It is difficult to understand some concepts, behaviors, functionality or other aspects of a specification without informative interpretations to aid the reader. Providing the reader with additional information beyond the specification’s prose, can only help in achieving implementation and interoperability.
Techniques
It is up to the Working Group to determine the best way to illustrate the scope and other parts of the specification. Typically, the nature of the specification influences the type of examples, uses cases, graphics, etc that make sense.
- Develop use cases to illustrate the specification scope. Use easy-to-understand narrative to describe situations that are applicable to the specification.
- Provide example:
- for each behavior or functionality that was resolved from an issue
- to illustrate the meaning of abstract notations (e.g., BNF)
- for each chapter in the specification
- Describe the language features through numerous examples and compliment them by references to the normative texts
- Reference a non-normative tutorial document which includes informative explanation of concepts, behavior, or functionality.
- Provide non-normative references to resources such as books, specification annotation, test sets. These references provide annotations to the specification, pictorial illustrations, and explanations of specification rules.
Examples
For markup specifications, provide at least one example of each markup construct; illustrate each transformation capability with an example showing input and output.
SVG 1.1 [SVG11]: For each element of the SVG specification, there is a verbose definition of the element, the DTD definition, the attribute definitions and an example. For instance, in the definition of the element rect, there are precise examples with the markup to generate a rectangle, a rendering of the markup as an image to help people visualize it and a separate file with the said markup.
HTML 4.01 [HTML401]: The HTML 4.01 specification has been designed in a very educative way. By its design, the specification has very good examples.
2.2 Requirement A:
Identify who or what will implement the specification.
What does it mean? Clearly identify the class of products (i.e., type of products or services) to which the specification applies. If multiple classes of products are targeted by the specification, make sure each are described. Examples of classes of products include: content, producer of content, player, protocol, API, agent, guidelines.
Why care? It helps define the scope of the specification and is needed when defining conformance. It also helps the reader know what is being targeted by the specification – that is, to discover and focus on what they have turned to the document for and avoid what they may find immaterial.
Techniques
- Give the classes of products in the specification:
- Think about all the types of products or services that will implement this technology, group those that are similar and/or basically achieve the same purpose, and determine the generic name for the group. This would be the class of product.
- List these classes of products in the specification.
- Describe them as part of the scope.
Examples
The conformance section of Ruby [RUBY] is very explicit and detailed about classes of product. For each of these classes, Ruby conformance
section defines a set of rules, the implementers must
respect. It defines rules for markup, DTD, document, module, generator,
interpreter.
2.3 Normative (and non-normative) references
A specification is rarely written in isolation. It inherits from previously defined technologies and might set the future of other specifications by defining their base. Then it is essential to clearly defines what is the nature of the specifications (normative, informative), the technology refers to and the implications of these references for the future of the technology itself.
As a side note, there is also an interest to study and understand the conformance model of the technology which is developed in order to minimize the difficulties of other specifications using it in a conformant way.
2.3 Requirement A: Make a list of normative references.
What does it mean? A specification is rarely developed from scratch: it usually relies on other technologies defined in different specifications. The Working Group has to identify any specifications which defines the core technologies of the developed technology.
Why care?
For the Working Group, it has an immediate benefit: “do not reinvent the wheel”. Using features which are already defined in other documents helps to minimize the size of the document which is developed and avoid too many ambiguities by rewriting the same concepts.
For the implementers, it has the huge benefits of knowing which part of the specification is based on another technology. It makes clear what are the implications for conformance. It may help them to minimize their work by using conformant libraries already implemented elsewhere.
For the users, it might help them to understand where the technology is coming from and therefore how to use it in combination with other technologies they might already know.
Examples
Most W3C specifications contain a list of normative references, which are clearly identified at the end of the document.
2.3 Good Practice B: Do systematic reviews of normative references and their implications.
What does it mean? Each time, a normative reference is added to the specification, it has deep implications on the way the technology is defined. Each choice has to be reviewed and checked for the consequences in terms of time, consistency, precision, and use of the technology in specific conditions.
Why care? A specification defines a technology which will be used for a long time. The choice of precise and exact normative references is thus fundamental. Using a normative reference which evolves over time might endanger the specification or other specifications relying on it.
For the Working Group, reducing the degree of ambiguity or variation in the normative references minimizes or removes the possibility of misunderstanding. For implementers, it removes ambiguities and contradictions between different sets of technologies. It creates a stable environment into which they can make stable developments.
Examples
For the sake of illustration, we give here a list of cases that illustrates some of the problems and their implications for the technology. It is not exhaustive review of all possible cases. Imagine, a technology has to use the notion of URI or URI-references. The technology is already defined in a specification which is called RFC2396 and has for title “Uniform Resource Identifiers (URI): Generic Syntax”.
Let's create a simple definition and give examples of possible problems that arise from this definition:
The value of the attribute is a URI as in [RFC2396]
which can be expressed by
...="http://www.example.org/#foo"
...="http://[3ffe:2a00:100:7031::1]/"
...="http://666.666.666.666/"
...="foo"
...="http://www.example.org/~anaïs-nin"
Precise designation and reference: The first example is illegal as the example uses a URI Reference as opposed to only a URI, RFC 2396 clearly distinguishes between those constructs. It would have been better to say:
The value of the attribute is a URI Reference as defined in section 4 of [RFC2396]
Superset of the reference and interpretation: RFC 2396 does not include support for IPv6 literals, the syntax has been introduced in RFC 2732 which does not update RFC 2396. It is not correct to assume that it does even if it seems logical. Do not interpret the intention of the external reference.
Contradictory choices and references: Using the concept of URI-reference as a normative reference and then in the prose of the specification, define that it is an error to use it.
4. Managing Variability
Specifications allow for variation between conforming implementations for different reasons, e.g., adaptation to hardware capacities and extensibility. Variability, while it can provide for broader usage of the technology, may impede interoperability. Watch out for excessive variability – that which goes beyond what is needed. Look for a balance between what is needed to allow for flexibility while still achieving the desired interoperability.
This section gives advice on finding the right balance; the reader
will also benefits from reading, Variability in Specifications
[VIS] which goes into more details on the analysis of
this variability.
4.1 Subdivide
Subdividing the technology should be done carefully. Too many divisions complicates conformance and can hinder interoperability by increasing the chances of conflict with other aspects of the specification (e.g., other subdivisions). Be smart when dividing the technology so that it is not excessive and provides a positive impact on implementation and interoperability. The benefits of subdividing should outweigh the drawbacks.
Benefits: Subdividing can
- make the technology easier to implement
- facilitate incremental implementation
- increase interoperability by focusing the technology on specific needs
- help organize the structure of the technology
- provide better normative guidance than recommended or optional features in the "core" spec
- provide names for feature bundles, facilitating automated negotiation between sending and receiving products
Drawbacks: Too many divisions can
- complicate conformance – need to account for interrelationships with other subdivisions and variability (e.g., extensibility)
- hurt interoperability – increases likelihood of incompatible implementations
- increase misinterpretation or cause conflict of requirements due to multiple or duplicative requirements.
4.1 Good Practice A:
Create subdivisions of the technology when warranted.
What does it mean?
It may make sense to subdivide the technology into related groups of functionality to target specific constituencies, address specific capabilities or hardware considerations, provide for incremental implementation, facilitate usability, etc.
Why care?
For some specifications (e.g., huge, multi-disciplined), bundling functionality into named or anonymous packages can
- provide an additional level of scoping control,
- improve readability and the ability to find areas of interest, and
- facilitate implementation and interoperability, since implementing the entire, monolithic specification may be impractical and undesirable
Techniques
- Use profiles. Profiles are subsets of a technology tailored to meet specific functional requirements of application communities. The specification may define individual profiles, and may also define rules for creating new profiles. An individual profile defines the requirements for classes of products that conform to that profile. Rules for profiles define validity criteria for profiles themselves.
- Use functional levels (aka levels). Functional levels are a hierarchy of nested subsets, ranging from minimal or core functionality to full functionality. Levels are a good way to facilitate incremental development and implementation.
- Use modules. Modules are discrete collections of semantically-related units of functionality that do not necessarily fit in a simple hierarchical structure. Use modules when functionality can be implemented independently of one another e.g., audio vs video module. It is common to have implementers pick and choose multiple modules to implement.
Examples
CSS and DOM technologies are examples where levels are the result of progressive historical development and technology enrichment and are realized in a series of specifications.
4.1 Requirement B:
If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.
What does it mean?
Regardless of the subdivision technique (i.e., profile, level or module), state whether one or more of the subdivisions is required for conformance.
Why care?
Subdividing the technology affects and can complicate conformance with all the various combination of choices it provides. Thinking about the various possibilities helps to structure the conformance model, taking into account how the subdivision can affect various classes of products. Implementers as well as users need to know what is mandatory, optional, prohibited or conditional with respect to choosing what to implement and still be conforming.
Techniques
In the conformance clause, list the subdivisions that are mandatory for conformance. To help build this list, consider the following questions for each subdivision:
- Can an implementation conform without implementing the subdivision?
- Does the subdivision apply to specific classes of products and not to others?
- Is the subdivision dependent upon other subdivisions (that is, if it is implemented must others also be implemented)?
Examples
Content can be required to conform to one of the subdivisions (e.g., profiles) or it may be conformant to the specification independently of a subdivision. The question arises for a producer (of content): is it conforming if it generates content that is otherwise valid but does not conform to the subdivision.
WCAG 1.0 [WCAG10]
defines three levels of Conformance depending on the levels.
XHTML Modularization [XHTML-MOD]
defines minimal requirements for including certain basic modules when designing a conformant XHTML Mod document.
4.1 Requirement C:
If the technology is subdivided, then address subdivision constraints.
What does it mean?
This is a corollary to the Requirement above. Beyond being mandatory or not, subdivisions usually have conformance consequences due to minimal or new requirements, restrictions, interrelationships, and variability, etc. As part of the conformance clause, describe the constraints associated with each subdivision
Why care?
Creating subdivisions can get complicated, not just for the specification editor but for implementers who must pick and choose from the set of subdivisions. Well designed subdivisions that convey the conditions, constraints, interrelationships, etc. can improve the clarity and understanding of the specification, conformance to the specification and facilitate implementation and interoperability.
Techniques
In the conformance clause, describe the conditions or constraints on subdivision usage. To help accomplish this, model or graph the subdivisions indicating the following that applies:
- Atomicity of the subdivisions: Represent each subdivision showing its atomicity.
- Mandatory subdivisions: Label the subdivisions that are mandatory
- Minimal requirements: List minimal requirements for each subdivision.
- Dependencies among subdivisions: Show dependencies and interrelationships of the subdivisions. For example, modules that requires and builds on functionally related modules, i.e., modules that require modules from other functional areas.
- Conditions and constraints on subdivisions groups: Indicate conditions and constraints for combined occurrences of subdivision pairs or groups:
- Conditions or constraints associated with specific classes of products: Indicate which conditions and constraints are applicable to specific classes or products.
- Other conditions or constraints beyond these: Indicate any other conditions or constraints.
4.1 Good Practice D:
If the technology is profiled, define rules for creating new profiles.
What does it mean?
If profiles are used and profiles can be developed outside the specification itself, then provide the rules for creating these derived profiles. These profile rules provide instructions for building profiles (e.g., requirements on structure, functionality, encoding, etc.). Derived profiles should not contradict predefined profiles, if there are any in the base specification.
Why care? Well-defined rules facilitate the creation of derived profiles that are well-specified, implementable, testable, and can foster a better interoperability across profiles. If these rules are defined and followed, then the derived profile conform to the specification.
Techniques
- Create two particular profiles
- Identify the common requirements in these two profiles
- Identify the rules that you have followed to create these profiles and write them down
- Try to create a third profile using the defined rules
4.2 Optionality and Options
Options in specifications provide implementers the freedom to make
choices about
- whether or not to support a well-defined feature,
- which value or behavior to choose from a well-defined enumerated set of possibilities,
- implementation dependent values or features.
These choices also called discretionary items, give implementers of the technology the opportunity to decide from alternatives when building their applications and tools.They describe or allow optionality of behavior, functionality, parameter values, error handling, etc. They may be considered necessary because of environmental conditions (e.g., hardware limitations or software configuration), locality differences (e.g., language or time zones), dependencies on other technologies, or the need for flexibility.
Although there are perceived benefits to providing optional features, there is also a downside: optional features increase the variations that can exist among
implementations. The greatest way to undo the utility of a specification is with too many optional features. Basically, different implementations may use different combinations of optional features. This makes comparisons between
implementations difficult as well as complicates conformance testing and
increases the chance of non-interoperable implementations.
Story:
A concise XSLT 1.0 [XSLT10] example: implementers have been granted separate discretion about all of the following aspects of creating attributes in the output:
- Whether to raise an error when the supplied name is not a valid QName
- Whether to raise an error when an attempt is made to create an attribute after children of the element have been created
- Whether to raise an error when an attempt is made to create an attribute on a node that is not an element
- Whether to raise an error when the content of an attribute is not plain text
- Whether to raise an error when two attribute-sets of the same precedence contain an attribute of the same name
- Whether to raise an error when attempting to create an attribute directly under the root of a result tree fragment
In each case, there is one prescribed behavior for an implementation that chooses not to raise an error. Thus, the 6 separate binary choices give rise to 64 different possible behaviors for conformant processors. Typically, an implementer would be content to make a more global choice about raising errors when there is an attempt to create non-well-formed XML results.
4.2 Good Practice A:
Make sure there is a need for the optional feature.
What does it mean? Examine the reason for the optional feature - is it to address a real, existing need? Should it really be optional or made a mandatory part of the specification? Be careful not to provide optional features in anticipation for something that sounds like a good idea but will probably never be realized - ask the implementers if they ever plan to need this. Think about the implications of both implementing the optional feature and of not implementing it. Don't make something an option just because the Working Group can't decide on what to do or can't reach consensus. As the specification progresses, if the feature is not implemented, consider removing it.
Why care? A concise list of optional features helps to keep the specification focused and greatly increases the likelihood of obtaining interoperable solutions. Ensuring that only necessary optional features are contained in the specification also makes the job of the implementer easier and reduces costs.
Techniques
- Make a list of use cases with the optional feature.
- Look at the optional feature and each class of product. Is it something that this class of product would implement? Consider if it really is an option - perhaps, for this class of product it isn’t really an option but should be mandatory.
- Develop an analyzer or set of tests to determine if options are needed. Use the analyzer/tests to capture what implementations are doing – are they doing basically the same thing or is there variety and is that variety desired.
Story:
As part of its exit criteria for Candidate Recommendation, a Working Group created a set of tests to 'test the specification'. The tests were able to show where there was need for optionality (e.g., diversity among implementations and flexibility justified) and where it was possible to narrow the choices (e.g., implementations used a much narrower set of values than what was permitted).
4.2 Good Practice B:
Clearly identify optional features.
What does it mean? When introducing an optional feature in the specification, label it as such, so that it's easy to find all the optional features defined in the specification.
Why care? Options can be useful, but non-judicious use of optional features increases the variability among conforming implementations. In order to minimize the unnecessary optionality, it is a good idea to provide an easy way to identify them. The use of labels for optional features also helps in constructing pro forma, conformance claims, comparisons between two implementations, reports to the W3C Director about implementations, etc.
Techniques
Options can be tagged in many ways. Any technique that distinguishes the optional feature from the required feature is acceptable. Some possibilities include:
- listing optional features in a separate section;
- specifying optional features in a different font (be careful of accessibility and printing problems);
- including a unique designation to identify the optional feature.
4.2 Good Practice C:
Indicate any limitations or constraints on optional features.
What does it mean? Provide as much information as possible to narrow the allowable choices and to increase predictability. For implementation dependent values or
features, if possible, provide a range or set of permitted values rather than
leaving it completely open. Design the extension mechanism to allow for the creation of extensions that do not interfere with conformance to the original specification.
Discuss the implications of either using the optional feature or not. It may be helpful to provide rationale for choosing one option over another or for not using the option at all. Consider the unintended consequence of the optional feature - on other optional features, other parts of the specification, on other specifications.
Why care? Narrowing choices and increasing predictability enhance the likelihood of interoperability since the sample space for the implementer to choose from is diminished. Narrow choices and providing more information also increases the chances of correct implementations since incorrect choices are eliminated. An enumerated list of values is one way to constrain the choice of optionality.
Techniques
For optional features, especially enumerated lists, make sure that the number of choices/options that can be implemented is known. Specifically, can zero, exactly one, or several of the allowable choices be implemented? Does this number depend on other parts of the specification or other chosen options?
Questions to consider include:
- What affect will implementing the optional feature have on a conforming
implementation, on interoperability?
- Is there any affect or negative consequence if the option is not
implemented?
- Must the option be implemented?
- Is there a default value for the option?
- Are there any dependencies, that is, the option can only be implemented
if certain conditions are true?
- Are the optional features mutually exclusive, that is, can one option override
and void another?
Examples
In XPath 2.0 [XPATH20] and its associated functions, the Working Group intends to require support for collation by Unicode code-point, and allow implementations to implement as many other collations as they wish.
4.3 Extensibility and Extensions
To accommodate changes in technology and information on the Web, a
specification can be designed for extensibility. A specification is
extensible when it provides a mechanism to allow an external party to create
extensions. Extensions incorporate additional features beyond what
is defined in the specification. However, extensions can compromise
interoperability if there are too many differences between implementations.
The impact of extensions can be mitigated through features specifically
designed to allow new functionality. These features provide a 'standard way
to be non-standard' by including hooks, conformance rules, or other
mechanisms by which new functionality may be added in a conforming way, designated as extensibility mechanism.
4.3 Requirement A:
Address Extensibility.
What does it mean? Extensions might be encouraged or discouraged by the Working Group. There is a benefit to addressing the value or danger of extensibility for the technology being developed. Formalizing the position of the Working Group by a clear defined section and prose removes ambiguities for the specification users about the possibility of developing extension or not.
Why care? There is a strong likelihood that implementers will want to extend the functionalities defined in the specification, because they have specific needs which are not covered by it. Defining clearly how these extended functionalities can be hooked in conformance implementations help ensure that extensions are defined in a consistent manner leading to predictable handling of extensions and minimize issues such as interoperability problems, minimal support, and harmonious future development.
The Working Group may consider that the technology is complete, self-sufficient and and doesn't need to be extensible. In this case, it is necessary to write this clearly in the specification and to explain why the technology is not considered extensible. It might be just for the social benefit of the community to ensure a maximum interoperability.
Techniques
- Create a section in the specification dedicated to extensibility
- Call it Extensions
- Make a table of contents entry for it
- Address the following good practices of this section
4.3 Good Practice B:
If extensibility is allowed, define an extension mechanism.
What does it mean? Extensions increase variability between implementations. Defining a mechanism helps to ensure extensions are defined in a consistent manner leading to predictable handling of extensions, including the ability to take appropriate actions (e.g., do the extension, ignore, or take a fall-back behavior).
Why care? By planning for extensions and designing a specification for extensibility, there is less chance that extensions will interfere with conformance to the base specification and a better chance at achieving interoperability. Conversely, there may be areas in a specification that would not benefit from extensibility and extensions are strictly forbidden (e.g., permissible characters in XML 1.0 names for elements and attributes, most of the built-in datatypes in Schema Part 2). This is called strict conformance. Strict conformance is defined as conformance of an implementation that employs only the requirements and/or functionality defined in the specification and no more.
Reasons for designing extensibility into a specification include:
- providing a stable, useful framework to manage the rapid pace of
technology change,
- reducing the chances that extensions will interfere with conformance and
increasing the chances for achieving interoperability,
- providing the ability to 'test-drive' new functionality that may
migrate into future specifications,
- enabling implementers to include functionality that they consider to be
required by their customers.
Techniques
Technology and
application needs dictate the best strategy for enabling
extensibility.
When designing for extensibility, it can get complicated. Points to
consider that can impact design decisions include, but are definitely not limited
to:
- Address the use of extension in the conformance section.
- Give a well defined template to create extension.
- Verify that this mechanism prevents the creation of extension conflicting with the semantics of the specification.
- When needed, define the scope of extensions. (e.g., Are extensions authorized only for certain parts of the technology?).
- As an example, create a fake extension as an example for implementers what would be the right way to do it
- Indicate if extensions interact with other extensions.
- Indicate if extensions can be combined or are mutually exclusive.
- Indicate if extensions apply to a specification's profiles or modules and not the core part of the specification.
Examples
Mechanism defined within the specification, extension indicator, error handling instructions
XSLT 1.0 [XSLT10] provides extension mechanisms that allow an XSLT style sheet to determine
whether the XSLT processor by which it is being processed:
- has implementations of particular extensions available,
- and to specify what should happen if those extensions are not available.
It defines two boolean functions: function-available (QName) and element-available (QName) that must be present in every implementation. These functions inform the XSLT processor that there is an extension, therefore the XSLT processor can return a value of false and provides handling instructions (e.g., signal an error, perform fallback and not signal error), if the extension is not available.
WSDL 2.0 [WSDL20] defines binding extension elements which are used to provide information specific to a particular binding. It is a two-part extensibility model based on namespace-qualified elements and attributes. It provides the syntax and semantics for signaling extensions. Extension elements can be marked as mandatory, meaning that they MUST be processed correctly by the WSDL processor - i.e., either agree to fully abide by all the rules and semantics signaled by the extension or immediate cease processing (fault).
Mechanism based on another specification's extension mechanism
CC/PP exchange protocol based on HTTP Extension Framework [CCPP-EXCHANGE] defines a HTTP extension to exchange
CC/PP descriptions effectively. The CC/PP exchange protocol conforms to
HTTP/1.1 and is a generic extension mechanism for HTTP 1.1 [HTTP11] designed to inter-operate with existing HTTP applications. The CC/PP exchange protocol uses an extension declaration to indicate that an extension has been applied to a message and possibly to reserve a part of the header namespace. It provides rules for which of the HTTP Extension Framework [HTTP-EXTENSION] extension declaration strengths and extension declaration scopes to use and defines the syntax and semantics of the header fields.
OWL Reference [OWL-REF] is a vocabulary extension of RDF Semantics (See section 6 in [RDF-MT]). OWL imposes additional semantic conditions on RDF called semantic extensions of RDF. These semantic extensions conform to the semantic conditions for simple interpretations described in the RDF Semantics Recommendation. The OWL semantics is consistent with RDF semantics, but OWL when understood as RDF is 'incomplete' versus the same OWL when understood as OWL. Thus, by understanding OWL more is learned and nothing that is learned contradicts what is learnt by RDF alone.
4.3 Good Practice D:
Define error handling for unknown extensions.
What does it mean? Include error handling instructions for when an extension is not available or understood.
Why care? When using a strict conforming application, users might have to deal with documents, data which are considered invalid because they are containing errors, or they are extended. Developers need to know what is the expected the behavior of the application in such context.
Techniques
There are typically two approaches: (see section 4.2.3 Extensibility from Architecture of the World Wide Web, First Edition [WEB-ARCH])
- Must ignore: ignore any content it does not recognize. Must ignore can be further refined, requiring that the unknown item be passed through unchanged to the next downstream process, while other technologies simply discard it.
- Must understand: treat unrecognized markup as an error condition.
A good way to handle these two approaches is to have a way in the syntax to distinguish which behavior is expected, e.g., mustUnderstand attribute in Soap 1.2
Don't forget to address all the classes of products. For example, an authoring tool and a rendering tool might have to behave in a different way or not.
4.4 Deprecation
The need for deprecation comes about when there are features (e.g., function argument, element, attribute) defined in the specification that have become outdated and are being phased out, usually in favor of a specified replacement. It may mean for instance that the feature is still there and functional, but
- there is a better way of achieving the same thing and the Working Group prefers this better way is used
- or the feature is not being used and the Working Group wants to clean up the specification and eventually remove the feature.
From a user point of view, a deprecated feature is one that should not be used anymore, since it may be removed from future versions of the specification. Deprecated features are no longer recommended for use and may become obsolete and no longer defined in future versions of the specification.
4.4 Requirement A:
Identify deprecated features.
What does it mean? When a technology evolves, it is important to provide a list of the features being deprecated from the previous version of the specification.
Why care? It helps implementers know which features are expected to be obsoleted in the next version of the technology. This gives them the opportunity to adjust their implementation to phase out the relevant features, and provide new ways to accomplish the same task.
Techniques
- Create a list of all deprecated features
- Create a dedicated section for it
- Create a entry in the table of content going to this list
- For each deprecated feature, create a link to the appropriate definition in the specification
Examples
HTML 4.01 [HTML401]: The specification has a full list of elements and attributes. The deprecation status is given in the two lists. There is an entry in the table of content to these two lists. Each element/attribute is linked to its definition in the specification
4.4 Requirement B:
Define how deprecated feature is handled by each class of product.
What does it mean? By deprecating a feature, the Working Group indicates its desire that the feature disappear from a future version of the specification. The motivation may be to convert an old feature to a newer one or to remove an old, dangerous, redundant or undesirable feature. Regardless of the reason, it is important to define the affect this has on implementations that may encounter this feature (e.g., consumer products such as user agents or producer products such as authoring tools). Will use of the deprecated feature be tolerated? Will it signal an error or a warning? Typically, it is expected that a deprecated feature would not affect a consumer (e.g. user agent), while a producer (e.g. authoring tool) should issue a warning.
Why care? Defining how deprecated features are handled provides a smoother transition for the users of the specified technology, and ensure more consistency of the behavior across implementations. It is also particularly important for implementations that needs to support different versions of the specification.
For instance, the specification may require that an implementation
supports both the features of the new and the old specifications, or
suggest a converting mechanism.
Techniques
- Consider the effect of deprecation on all classes of products that implement the specification (e.g., authoring tools, converter, user agents).
- Define how it affects conformance
Examples
HTML 4.01 [HTML401]:
In the conformance section of HTML 4.01, there is the definition of deprecation and what user agents should do. The behavior for other kind of products is not defined though.
User agents should continue to support deprecated elements for reasons of backward compatibility.
4.4 Good Practice C:
Explain how to avoid using a deprecated feature.
What does it mean? Deprecating a features implies that its use is discouraged, often because there is a better technique available to achieve the same result. For each deprecated feature, it is necessary to explain how implementers and users can avoid using it. It might be helpful to give additional information providing insight into the deprecation motivation.
Why care? Examples and information about each deprecated features help users to smoothly evolve toward the new version of the technology, understanding its benefits. This enables a faster adoption of the technology.
It helps implementers understand the rationale for implementing the new technology, to implement an alternative mechanism, and to tool tips or conversion scenarios to help users with the transition.
Techniques
- For each deprecated feature, give one or more examples showing the old way and the new way.
Examples
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 this
means with respect to conformance to XML 1.0 and Namespaces as well as the
affect on other specifications (i.e., DOM, XPath).
HTML 4.01 [HTML401] gives numerous examples on how to avoid the markup which was used in previous versions for deprecated elements.
4.4 Good Practice D:
Identify obsolete features.
What does it mean? A feature which has been deprecated in a previous version of the specification was at risk of being removed. Making it obsolete indicates that the feature is no longer in use and removed from the current version of the technology. Providing a list of obsolete features informs implementers and users what is no longer in the specification.
Why care? It gives a clear message to users and implementers that obsolete features are forbidden and not part of the specification anymore. It helps avoid the creation of documents mixing old and new techniques which would be invalid.
It helps avoid name clashing. When an extension to a technology is created, implementers are likely to use syntax token for their extended features name. Giving the name of obsolete features helps implementers to avoid using the names of previous features which are now obsolete.
Techniques
- Create a list of all features that are obsolete.
- Create a dedicated section for it.
- Create a entry in the table of content going to this list.
- For each deprecated feature, create a link to the appropriate definition in the previous specification.
Examples
HTML 4.01 [HTML401]: The specification has a full list of elements and attributes. The obsolete status is given in the two lists. There is an entry in the table of content to these two lists. Each element/attribute is linked to its definition in the specification
HTML 4.01, Appendix A: Changes lists the elements that are obsolete 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.
4.5 Error Handling
4.5 Good Practice A:
Define an error handling mechanism.
What does it mean?
For a language, address what effect an error (be it syntactic or
semantic) in the input has to a processor of this language.
For a protocol, address how should behave a party to this protocol when
a bogus message is received.
Why care?
There are many reasons a system may fail; to make a technology reliable,
it is crucial to define how it should react to bogus input.
Defining error handling also makes it possible for a user of the
technology to react appropriately to the error condition.
Techniques
Different methodologies exist to handle er
