The essentials of a specification

This note is a little motherhood and apple pie about how a specification should be couched so as to clearly add a new well-defined piece to the technology.

A technical specification defines something. The document must specify the thing being defined as well as give its definition: a "left hand side" as well as a "right hand side". Both must be done quite precisely.

Typically, technical specifications for the web specify a language or a protocol. A protocol is a language for messages, plus a set of constraints on the sequence of messages. A language is a set of symbols, the syntactic constraints on the way their are combined, and the semantics of what they "mean" at some (possibly more than one) level. (See also Meaning of web documents)

The test of a good specification is that it clearly defines what implementation (document, message, program) conforms, and of course that it ensures by its design that whatever conforms works to provides the required function.

The left hand side

The document should state what sort of things is being defined. It should introduce a new term which characterizes that which conforms to the specification. Examples of a conformance term could be

A well-formed XML 1.0 document

A conforming HTTP 1.1 server

An xml-schema-valid XML document

A W3C/WAI "AAA" accessible web site

The SVG 1.0 language

The same specification document can define more than one term. such as a "strictly conforming WWidget" and a "loosely conforming WWidget" but one should beware of diluting the "WWidget" brand.

As systems become more self-describing, the term is given a formal identifier. Examples could be

The MIME type "image/svg1"

The XML Namespace "http://www.w3.org/1999/asdf-2-0"

In this case where a MIME type or namespace has an identifier, then this is obviously the crucial term to use to be unambiguous.

Wherever possible, conformance phrases will be grounded in the Web: identified by a URI.

The Right Hand Side

More has already been written on this, and most of it seems to be in consensus in the W3C.

It is important to remember what you are defining as you write the text. For example, if you are defining a "foo-valid document" then using "is invalid" in the text can be assumed to apply to this but "is incorrect" or "is wrong" or "produces an error" does not unless the language is explicitly linked to the conformance term.

A good spec similarly pays attention to:

The distinction between the use of MUST, as opposed to MAY (etc., see Bradner's BCP14)

The use of this distinction in defining the conformance term precisely;

The distinction between normative and non-normative parts of the specification.

When defining a language, whenever possible specify directly the meaning rather than the sort of thing you would expect some software to do with it. Typical behaviors of an agent may be very useful to explain the intent non-normatively.

For example,

"x" indicated that the check is void

is better than

"x" indicates that the check should be rejected with a fatal error.

You can tell people what something means, you can't tell them what to do about it, unless you are defining a protocol. When defining a protocol, then the constraints should ideally be given as a state transition diagram or table to make them totally clear.

When defining a message which in fact binds to human social entities, then this must be clear. You could end up in court explaining it if not. ("The MMTP protocol defines the meaning of a message sent by or on behalf of a party herein referred to as the "debtor" to a party referred to as the "creditor". The creditor is identified by the foo-email-address...)

When defining a part of a specification deliberately to be similar to another specification,

Make it clear that you have noticed the similarity;

Make it clear whether the similarity is exact and if not where not (and why not);

Ideally, it clear that the existing specification is being referred to normatively and is definitive, and that what is in this specification is a non-normative copy for information only.

Make it clear whether the use in this specification will track any new version of the referenced specification.

Think about whether there is any way in which such changes could break this system.

If necessary negotiate constraints with the authority for changes to the referenced specification.

Test questions

A few examples of things to ask about a spec -- though generalization is difficult.

Does the spec give enough information to determine, for any arbitrary object, whether the conformance term applies to it?

Could you write a program to test conformance?

Is conformance alone enough to ensure that systems build using this language will function as intended and with integrity?

Can you prove important properties of the system from the state transition tables etc?

So much for another bit of folklore. Comments, suggestions welcome.

References

S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP0041

These are some of the raw bits of standards which I picked up from Peggie Rimmer at CERN, and from working with IEEE, IETF and W3C specifications over the years. I am sure others have written books on it. Comments, suggestions welcome