Why Should a Protocol Reference Define Normative Terms?
From the earlier reference collection. Read the current software blog.
Defined normative terms distinguish mandatory requirements from recommendations and options, helping independent implementations make compatible choices.
Words can carry protocol weight
In ordinary writing, words such as “must,” “should,” and “may” can sound like variations in emphasis. In a protocol specification, they can define different levels of obligation. If a reader cannot tell whether a sentence is a requirement or advice, two implementations may make different choices while each believes it followed the document.
A reference should define its normative vocabulary near the beginning and use it consistently. The GTFS schedule reference, for example, explains that its uppercase requirement terms follow a named conventions framework. That gives readers a basis for interpreting those words throughout the document rather than relying on tone or context.
Make conformance checkable
A mandatory rule should be stated so an implementation can be checked against it. If a field is required for every record, a validator should be able to identify a record that omits it. If a behavior is recommended, a reader should understand that another choice may still conform, even if it is less interoperable.
Consider a sentence saying clients “should preserve unknown extension fields.” If the specification defines “SHOULD” as a strong recommendation with allowed exceptions, implementers can preserve fields by default and document why a special case differs. Without that definition, one author may treat preservation as compulsory while another considers it a casual suggestion.
Separate requirements from rationale
Keep normative statements distinct from explanation. A sentence can say “A receiver MUST reject a missing identifier,” followed by a note explaining that the identifier is needed to associate a response with a request. The requirement guides conformance; the rationale helps readers understand its purpose. If examples and commentary accidentally introduce extra obligations, implementations may diverge over what the protocol actually requires.
Define whether keywords are case-sensitive and what to do when a term appears outside a normative context. Avoid using the same word casually in prose if readers could mistake it for a formal requirement. A brief conventions section can prevent repeated ambiguity later.
Help implementers handle gaps
Normative vocabulary also makes disagreements easier to resolve. Reviewers can point to a defined level of obligation, identify a genuine conflict, and propose a revision rather than debating how forceful a sentence sounds. When a specification leaves a behavior optional, say whether implementations need to advertise support or how peers discover the choice.
A protocol reference is a contract among independent implementers. Defining normative terms turns that contract into something readers can apply consistently, test, and discuss. It gives mandatory behavior, recommended practice, and permitted variation distinct roles, improving compatibility without making every implementation identical.