This was imported from the old wiki and has not been updated in many years.
This page is intended to capture current best practices for protocol specifications produced by the WG. The intent is for this page to evolve as WG contributors find topics to correct and new topics to add or remove. The page was started by Lou Berger, but any and all should feel free to modify.
A protocol specification defines formats (i.e., syntax) and related processing procedures (i.e., semantics). The objective of a standards track protocol specification is to ensure interoperable function across multiple independent implementations. RFC2026 and its related updates provides the formal definition and process for IETF RFCs.
The RFC editor has published guidelines and procedures, read them here.
Please read and follow RFC Editor’s limit on number of authors.
A specification should include both informative and normative text.
Informative text provides a narrative on the function / mechanisms defined in the document, generally covering:
(a) their motivation;
(b) an overview of the function provided and new definitions;
(c) and a more detailed description of new mechanisms and their operation.
Of course there is a balance that needs to be struck between providing informative context and the actual protocol specification.
Normative text defines formats used "on the wire" and the related processing procedures. Normative text provides conformance language using RFC2119 defined terms to ensure independent interoperable implementations.
RFC2119 defined terms are used to ensure independent interoperable implementations. If text doesn't impact interoperability, it shouldn't include RFC2119 defined terms.
A general rule to follow is that RFC2119 terminology should only apply to something which can be tested. In other words, if a conformance test can't be devised to match the related text, RFC2119 terminology isn't appropriate.
Informative narrative should never use RFC2119 defined terms. Their use is appropriate in definitions of formats (i.e., syntax) and the related processing procedures (i.e., semantics).
Consider if you want to avoid lower case versions of the terms as you’ll inevitably be asked if you made a mistake in not capitalizing the text – even in informative text. Alternatively, you may choose to look forward to telling the reviewer/WG Chair/AD/etc. that they are confused!
The choice of conformance terms needs to be considered carefully. When choosing between RFC2119 conformance terms, e.g., between “MAY”, “SHOULD”, and “MUST” (“NOT”), the impact to interoperability needs to be considered.
The terms “MAY” or “SHOULD” (“NOT”) can be used to define different possible behaviors as well as essentially optional function sub-sets. In general, optional functions in an RFC are to be avoided. Consider the case where functionality is referenced via an RFC number, when there are optional functions defined in that RFC, the RFC number alone is insufficient to identify the function or to ensure interoperable implementations of the RFC. Options should be removed from a document and either dropped or separately standardized.
When using “MAY” or “SHOULD” (“NOT”) the implications of one implementation making one choice interoperating with an implementation that makes that opposite choice needs to be considered. When there are implications, the implications must be specifically documented.
It is also important to consider the impact on the defined function. For example if only “SHOULDs” are used by an RFC defining a protocol extension, any implementation that existed prior to the RFC can be considered to be compliant with that RFC – just one that implements the non-recommended form of the RFC.
It is appropriate to use “MUST” (“NOT”), or (“NOT”) “RECOMMENDED” when specifying behavior “on the wire” that is required to deliver the function being defined. Here too, a RFC2119 defined term is used only to insure interoperability between implementations.
Examples are very helpful, both in general terms in relation to informative text and in specifics related to defined formats and procedures. But examples should never be used as a replacement for either informative or normative text.
Use and reference existing terminology wherever and whenever possible. Avoid introducing new terms/terminology. Particularly when there are existing terms - even if you don’t like or agree with them. If you really have something new, see if a qualified existing term can be used, e.g., TE LSPs.
A reference is needed at least the first time an existing technology/mechanism or technical term is used - and at the point it is used. This ensures that there is an unambiguous interpretation of the documents meaning and also highlights new definitions in the document.
The references section needs to be broken down into normative and informative references. Basically if the referenced material defines a protocol format or mechanism that is required in order to implement the mechanisms defined in the (your) document, the reference should be normative. If the reference just provides background material, it is informative. A rule of thumb, a reference that is itself of informative category, will be an informative reference. One can not reference an informational RFC as normative (this is called a down reference). Be careful in your selection of references, especially informative. This is not intended to be a google of all "information". And it is not intended to give visibility/citation credits to your favorite conference/research paper.
A protocol specification defines formats (i.e., syntax) and related processing procedures (i.e., semantics).
When defining new protocol formats, the formats need to be fully defined. Both format and field definitions are required. Separate formats should be provided for IPv4 and IPv6 formats. Every field, with their lengths should be explicitly defined. When introducing sub-objects/TLVs, their formats need to be fully specified. This includes the meaning, size and required processing of T(ype) and L(ength) fields. When possible, definition by reference is preferred.
Valid ranges and values of fields defined in the document must be defined. This is true even when new IANA registries are to be defined related to the fields, i.e., initial values are defined in the document not by IANA.
Don’t forget to include ABNF when modifying protocols that were defined using it, e.g., RSVP.
Formal processing procedures must be included for all formats and new mechanisms defined in a document. RFC2119 language must be used to ensure interoperable implementation. Ensure that you state what processing is and is not allowed/optional.
Error processing, and when appropriate, messaging must be included for errors that may impact interoperability. For example, how should a receiving node behave when an expected information element (Object, flag, etc.) is missing, or when a duplicate or unexpected expected information element (Object, flag, etc.) is received.
Do not repeat definitions or required processing in multiple places. This is true within a document, i.e., only has one place where syntax and semantics is formally defined (with RFC2119 language).
When extending existing protocols it is necessary to describe how the defined extension will interoperate with non-supporting implementation. Keep in mind that the document defining an extension cannot define behavior of an implementation that existed before, or doesn’t support, the extension.
Please don’t just say that your document doesn’t have any additional considerations. Identify the new information carried in the protocol and the new types of functions supported. Explore how new information and functions can be exploited. Related discussions in existing RFCs/documents should be referenced. When exploitation can be ameliorated through a document approach, please reference it. When this isn’t the case, there needs to be at least some discussion of mitigation.
IANA Considerations sections must follow RFC2360. Recommended values should no longer be included anywhere in a draft.
Additions to existing registries should provide the URL to the registry and provide information for all fields in the registry, in the format of the registry. See https://tools.ietf.org/html/draft-ietf-ccamp-wson-signaling-10#section-6 here] for a recent example.
New registries must include initial values, which are defined in the document. The current practice is to use an allocation policy as follows:
The registry should be established with registration policies of "Standards Action" for Standards Track documents, and "Specification Required" for other documents. The designated expert is any current <fill-in> WG chair.
Allocation policies can be found in RFC5226.
Once your document is stable, feel free to talk with the Chair about making an early allocation request. Keep in mind there are Conditions for Early Allocation. Notably:
Run it. Fix errors. Decide if warnings need to be fixed.
Also run spelling and grammar checking tools.