Network Working Group                                              G.  Scott
INTERNET DRAFT                            Defense Information Systems Agency
                                                                 August 1996

              Guide for Internet Standards Writers

Status of this Document

   This document is an Internet Draft.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet Drafts.

   Internet Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is not appropriate to use Internet Drafts as reference
  material or to cite them other than as a "working draft" or "work in

   To learn the current status of any Internet Draft, please check the
   ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
   Directories on (US East Coast),
   (Europe), (US West Coast), or (Pacific

   Distribution of this document is unlimited.

   This Internet Draft expires 21 February 1997.


  This document is a guide for Internet standard writers.  It defines those
  characteristics that make standards coherent, unambiguous, and easy to
  interpret.  Also, it singles out usage believed to have led to unclear
  specifications, resulting in non-interoperable interpretations in the past.

  This version of the document is a draft. It's intended to generate further
  discussion and addition by the STDGUIDE working group. Please send comments
  to or to the author.

Table of Contents

1    Introduction
2    General Guidelines
2.1  Protocol Description
2.2  Discussion of Security
2.3  Level of Detail
2.4  Protocol Versions
2.5  Decision History
2.6  Response to Behavior Out of Scope
2.7  The Liberal/Conservative Rule

draft-ietf-stdguide-ops-00.txt                                        [Page 1]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

2.8   Handling of Protocol Options
2.9   BNF Notation
2.10  Implementation Experience
3     Specific Guidelines
3.1   Packet Diagrams
3.2   Summary Tables
3.3   State Machine Descriptions
4     Glossary
5     Document Checklist
6     Author's Addresses
7     References

1  Introduction

  This document is a guide for Internet standard writers.  It offers
  guidelines on how to write a protocol specification with clarity,
  precision, and completeness.  These guidelines are based on both prior
  successful and unsuccessful IETF specification experiences.  Note that some
  guidelines may not apply in certain situations.

  The goal is to increase the possibility that multiple implementations of a
  protocol will interoperate.  Writing specifications to these guidelines
  will not guarantee interoperability.  However, a recognized barrier to the
  creation of interoperable protocol implementations is unclear

  Many will benefit from having well-written protocol specifications.
  Implementors will have a better chance to conform to the protocol
  specification.  Protocol testers can use the specification to derive
  unambiguous testable statements.  Purchasers and users of the protocol will
  have a better understanding of its capabilities.

2  General Guidelines

  It is important that multiple readers and implementors of a standard have
  the same understanding of a document.  To this end, information should be
  orderly and detailed.  The following are general guidelines intended to
  help in the production of such a document.

2.1  Protocol Description

  Standards must include a description of the purpose or context of a
  protocol's use.  The author of a protocol specification will have a great
  deal of knowledge as to the purpose of a protocol.  However, the reader is
  more likely to have general networking knowledge and experience, rather
  than expertise in a particular protocol.  Without an explanation of the
  purpose behind a protocol interpreting it is far more difficult, and a
  reader is more prone to error.

  This also applies to the algorithms used by a protocol.  A detailed
  description of the algorithms or citation of readily available references
  that give such a description is necessary.

draft-ietf-stdguide-ops-00.txt                                        [Page 2]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

2.2 Discussion of Security

  If the Internet is to achieve its full potential in commercial,
  governmental, and personal affairs, it must assure users that deliveries of
  their information transfers are free from tampering or compromise.
  Well-written security sections in standard protocol documents can do much to
  achieve that condition.  Implementors will find it easier to comply and do
  security.  Users can understand the security measures in place, and so have
  faith in the Internet.

  The security section should address several topics.  Very important is a
  description of the security issues the protocol solves, and what issues
  remain unsolved.  The effects the security measures have on the protocol's
  use and performance.  If possible, the discussion should address how much
  insurance the implementation of the security measures achieves.

  An author may not include security measures or considerations in the
  protocol standard.  If so, a detail explanation why they did not is
  necessary.  This discussion could present the reasons why the security
  issues are unresolvable at this time.  Alternatively, the author could
  present a case why security is unneeded when using the protocol.

  These security sections should be complete and stand alone.  If security
  measures are part of the general protocol text, they will be difficult to
  find.  If the security measures are not clear they may not be implemented,
  nor will a user be assured that they exist.

  Finally, it is no longer acceptable that security sections consist solely
  of statements similar to:  "Security issues are not discussed in this RFC."

2.3  Level of Detail

  The author should consider whether concise or verbose text best conveys the
  protocol's intent.  Concise text has several advantages.  It makes the
  document easier to read.  Such text reduces the chance for conflict between
  different portions of the specification.  The reader can readily identify
  the required protocol mechanisms in the standard.  Also, it makes it easier
  to identify the requirements for protocol implementation.  A  disadvantage
  of concise descriptions is that a reader may not fully comprehend the
  reasoning behind the protocol, and thus make assumptions that will lead to
  implementation errors.

  Longer descriptions may be necessary, however, to explain purpose,
  background, rationale, implementation experience, or to provide tutorial
  information.  This permits explanations at sufficient depth to insure
  understanding of the protocol.  Yet several dangers exist with lengthy
  text.  Finding the protocol requirements in the text is difficult or
  confusing.  An increased risk that the same mechanism may have multiple
  descriptions, which leads to misinterpretations or conflict.  Lengthy text
  is a challenge to the attention span of some readers.  Finally, it is more
  difficult to comprehend, a consideration as English is not the native
  language of the many worldwide readers of IETF standards.

draft-ietf-stdguide-ops-00.txt                                        [Page 3]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

  One approach is to divide the standard into sections:  one describing the
  protocol concisely, while another section consists of explanatory text.
  The STD 3/RFC 1122/RFC 1123 1812 provides examples of this method.

2.4  Protocol Versions

  Often the standard is specifying a new version of an existing protocol.  In
  such a case, the authors should detail the differences between the previous
  version and the new version.  This should include the rationale for the
  changes, for example, implementation experience, changes in technology,
  responding to user demand, etc.

2.5  Decision History

  In standards development, reaching consensus requires making difficult
  choices.  Including a discussion history and rationales for a decision can
  prevent future revisiting of these disagreements later, when the original
  parties have moved on.  Occasionally, the alternative not taken may have
  been simpler to implement, so including the logic behind the choice may
  prevent future implementors from taking nonstandard shortcuts.

2.6  Response to Out of Specification Behavior

  Recommend that detail description of the actions taken in case of behavior
  that is deviant from or exceeds the specification be included.  This is an
  area where implementors often differ in opinion as to the appropriate
  response.  By specifying a common response, the standard author can strike
  a blow against the law of unintended consequences.

  The standard should describe responses to behavior explicitly forbidden or
  out of the boundaries defined by the specification.  Two possible
  approaches to such cases are discarding, or invoking error-handling
  mechanisms.  If discarding is chosen, detailing the disposition may be
  necessary.  For instance, treat dropped frames as if they never were
  received, or reset an existing connection or adjacency state.

  The specification should describe actions taken when critical resource or
  performance scaling limits are exceeded.  This is not necessary for every
  case.  It is necessary for cases where a risk of network degradation or
  operational failure exists.  In such cases, a consistent behavior between
  implementations is necessary.

2.7  The Liberal/Conservative Rule

  A rule, first stated in RFC 791, recognized as having benefits in
  implementation robustness and interoperability is:

               "Be liberal in what you accept, and
                 conservative in what you send."

  Or establish restrictions on what a protocol transmits, but have few
  restrictions on what it will receive.  To avoid any confusion between the

draft-ietf-stdguide-ops-00.txt                                        [Page 4]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

  two, recommend that standard authors specify send and receive behavior

  The effect of this approach is that the description of reception will
  require the most detailing.  For implementations will be expected to accept
  any packet from the network without failure or malfunction.  Therefore, the
  actions taken to achieve that result, need to be laid out in the protocol
  specification.  Standard authors should consider not just how to survive on
  the network, but achieve the highest level of cooperation possible to limit
  the amount of network disruption.  The appearance of undefined information
  or conditions must not cause a network or host failure.  This requires
  specification on how to attempt acceptance of most of the packets.  Two
  approaches are available, either using as much of the packet's content as
  possible, or invoking error procedures.  Specify a dividing line on when to
  take which approach.

  A case for consideration is that of a routing protocol, where acceptance of
  flawed information can cause network failure.  For protocols such as this,
  the specification should identify packets that could have differing
  interpretations and mandate that they be ignored.  For example, routing
  updates contain more data than the tuple count shows.

2.8  Handling of Protocol Options

  Standards with many optional features increase the chance of
  non-interoperable implementations.  The danger is that different protocol
  implementations may specify some optional combinations that are unable to
  interoperate with each other.  Ideally, implementation experience purges
  options from the protocol while the document moves along the standard

  Options should only be present in cases where the protocol has an item that
  a particular marketplace requires, or because it enhances the product.  The
  protocol specification must explain the full implications of either using
  the option or not, and the case for choosing either course.  However,
  omission of the optional item should have no interoperability consequences
  for the implementation that does so.

  Certain cases will require the specifying of mutually exclusive options
  within a protocol.  That is, the implementation of an optional feature
  precludes the implementation of the other optional feature.  For clarity,
  provide details on when to implement one or the other, what the effect of
  choosing one over the other is, and what problems the implementor or user
  may face.  The choice of one or the other options should have no
  interoperability consequences between multiple implementations.

  The most prevalent current practice in the specification of Internet
  standards is to identify mandatory protocol features by the term "MUST,"
  and optional features by "MAY" or "SHOULD."

draft-ietf-stdguide-ops-00.txt                                        [Page 5]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

2.9  Notational Conventions

  Formal syntax notations can be used to define complicated protocol concepts
  or data types, and also to specify values of these data types.  This
  permits the protocol to be written with out concern on how the
  implementation is constructed or how the data type is represented during
  transfer.  The specification is simplifed because it can be presented as
  "axioms" that will be proven by implementation.

  The formal specification of the syntax used should be referenced in the
  text of the standard.  Any extensions, subsets, alterations, or exceptions
  to the formal syntax should be defined.

  The STD 11/RFC 822 provides an example of this.  In RFC 822 (Section 2 and
  Appendix D) the Backus-Naur Form (BNF) meta-language was extended to make
  its representation smaller and easier to understand.  Another example is
  STD 16/RFC 1155 (Section 3.2) where a subset of the Abstract Syntax
  Notation One (ASN.1) is defined.

2.10  Implementation Experience

  For a protocol to be designated a standard, it must go through the rigors
  of actual implementation.  This implementation experience should be
  captured in the final document.  For example, lessons learned from bakeoffs
  between multiple vendors.

3  Specific Guidelines

  The following are guidelines on how to present specific technical
  information in standards.

3.1  Packet Diagrams

  Most link, network, and transport layer protocols have packet descriptions.
  Recommend that packet diagrams be included in the standard, as they are
  very helpful to the reader.  The preferred form for packet diagrams is a
  sequence of long words in network byte order, with each word horizontal on
  the page and bit numbering at the top:

       0                   1                   2                   3
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
     |Version| Prio. |                   Flow Label                  |

  In cases where a packet is strongly byte-aligned rather than word-aligned
  (e.g., when byte-boundary variable-length fields are used), display packet
  diagrams in a byte-wide format.  Use different height boxes for short and
  long words, and broken boxes for variable-length fields:

draft-ietf-stdguide-ops-00.txt                                        [Page 6]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

                              0 1 2 3 4 5 6 7
                             |    Length N   |
                             |               |
                             +    Address    +
                             +   (N bytes)   +
                             |               |
                             |               |
                             +  2-byte field +
                             |               |

3.2  Summary Tables

  The specifications of some protocols are particularly lengthy, sometimes
  covering a hundred pages or more.  In such cases the inclusion of a summary
  table can reduce the risk of conformance failure by an implementation
  through oversight.  A summary table itemizes what in a protocol is
  mandatory, optional, or prohibited.  Summary tables do not guarantee
  conformance, but serve to assist an implementor in checking that they have
  addressed all protocol features.

  The summary table will consist of, as a minimum, four (4) columns:
  Protocol Feature, Section Reference, Status, and References/Footnotes.  Use
  additional columns if they further explain or clarify the protocol.

  In the Protocol Feature column describe the feature, for example, a command
  word.  Group series of related transactions under descriptive headers, for
  example, RECEPTION.

  Section reference directs the implementor to the section, paragraph, or
  page that describes the protocol feature in detail.

  Status indicates whether the feature is mandatory, optional, or prohibited.
  Provide a separate column for each possibility, or a single column with
  appropriate codes.  These codes need to be defined at the start of the
  summary table to avoid confusion.  Possible status codes:

          M  - must                       M - mandatory
          MN - must not                   O - optional
          S  - should                     X - prohibited
          SN - should not

  Use the References/Footnotes column to point to other RFCs that are
  necessary to consider in implementing this protocol feature, or any
  footnotes necessary to further explain the implementation.

  RFCs 1122 and 1123 provide examples of summary tables.

draft-ietf-stdguide-ops-00.txt                                        [Page 7]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

3.3  State Machine Descriptions

  A convenient method of presenting a protocol's behavior is as a
  state-machine model.   That is, a protocol can be described by as a series
  of states resulting from a command, operation, or transaction.
  State-machine   models define the variables and constants that establish a
  state, the events that cause state transitions, and the actions that result
  from those transitions.  Through these models, understanding the dynamic
  operation of the protocol as sequence of state transitions that occur for
  any given event.  Detailed text description of the state machines is
  necessary.  Also, recommend the use of diagrams, tables, or timelines to
  detail state transitions.

  When using a state transition diagram, show each possible protocol state as
  a box connected by state transition arcs.  Label each arc with the event
  that causes the transition, and, in parentheses, any actions taken during
  the transition.  The STD 5/RFC 1112 provides an example of such a diagram.
  As ASCII text is the preferred storage format for RFCs, only simple
  diagrams are possible.  Tables can summarize more complex or extensive
  state transitions.

  In a state transition table, read events vertically and states
  horizontally.  Represent state transitions and actions in the form
  action/new-state.  Use commas to separate multiple actions, and go on
  succeeding lines as required.  Present multiple actions in the order they
  must be executed, if relevant.  Letters that follow the state indicate an
  explanatory footnote.  The dash ('-') indicates an illegal transition.  The
  STD 51/RFC 1661 provides an example of such a state transition table.  The
  initial columns and rows of that table are below as an example:

        | State
        |    0         1         2         3         4         5
  Events| Initial   Starting  Closed    Stopped   Closing   Stopping
   Up   |    2     irc,scr/6     -         -         -         -
   Down |    -         -         0       tls/1       0         1
   Open |  tls/1       1     irc,scr/6     3r        5r        5r
   Close|    0       tlf/0       2         2         4         4
    TO+ |    -         -         -         -       str/4     str/5
    TO- |    -         -         -         -       tlf/2     tlf/3

  The STD 18/RFC 904 also presents state transitions in table format.
  However, it lists transitions in the form n/a, where n is the next state
  and a represents the action.  The method in RFC 1661 is preferred as
  new-state logical follows action.  Also, this RFC's Appendix C models
  transitions as the Cartesian product of two state machines.  This is a more
  complex representation that may be difficult to comprehend for those
  readers that are unfamiliar with the format.  Recommend that authors
  present tables as defined in the previous paragraph.

draft-ietf-stdguide-ops-00.txt                                        [Page 8]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

  A final method of representing state changes is by a timeline.  The two
  sides of the timeline represent the machines involved in the exchange.
  List the states the machines enter as time progresses (downward)  along the
  outside of timeline.  Within the timeline, show the actions that cause the
  state transitions.  An example:

            client                                     server

               |                                          |
               |                                          |   LISTEN
   SYN_SENT    |-----------------------                   |
               |                       \ syn j            |
               |                        ----------------->|   SYN_RCVD
               |                                          |
               |                        ------------------|
               |        syn k, ack j+1 /                  |
   ESTABLISHED |<----------------------                   |
               |                                          |

4  Glossary

  Internet standards are to use the following terms.  Deviations from the
  definitions given are discouraged, as it will likely cause
  misinterpretations among readers.


  This word defines the existence of an item that is optional.


  This word defines the existence of an item that is an absolute requirement
  of the specification.


  This phrase prohibits the use of the item.


  This word specifies that implementation of an item is discretionary.


  This word specifies an item that there may exist valid reasons in
  particular circumstances to ignore.


  This word specifies an item that is an absolute requirement of the

draft-ietf-stdguide-ops-00.txt                                        [Page 9]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996


  This word defines the existence of an item that there may exist valid
  reasons in particular circumstances to ignore.


  This phrase means that there may exist circumstances when the described
  behavior is acceptable or even useful.  Even so, describe the full
  implications so that the implementor can carefully weigh the pros and cons
  of the behavior.

  The above definitions are of a "contractual" nature.  This RFC does not
  define technical terms.  These definitions have been evolving with
  technology.  Extensive and detailed technical definitions in documents aid

5.0 Document Checklist

  The following is a checklist based on these suggestions which can be
  applied to a document:

   o Does it explain the purpose of the protocol?
   o Does it reference or explain the algorithms used in the protocol?
   o Does it give packet diagrams in recommended form, if applicable?
   o Does it use the recommended meaning for any of the terms defined in the
     glossary above?
   o Does it separate explanatory portions of the document from requirements?
   o Does it describe differences from previous versions, if applicable?
   o Does it give examples of protocol operation?
   o Does it specify behavior in the face of incorrect operation by other
   o Does it delineate which packets should be accepted for processing and
     which should be ignored?
   o Does it consider performance and scaling issues?
   o How many optional features (MAY, SHOULD) does it specify?  If more than
     [X], does it separate them into option classes?
   o Have all combinations of options or option classes been examined for
   o If multiple descriptions of a requirement are given, does it identify
     one as binding?

6. Author's Addresses

   Gregor D. Scott
   Director, Defense Information Systems Agency
   Ft. Monmouth, NJ  07703-5613  USA

   Phone: (908) 532-7726
   Fax:   (908) 532-7723

draft-ietf-stdguide-ops-00.txt                                       [Page 10]INTERNET DRAFT       Guide for Internet Standards Writers          August 1996

7. References

RFC 791   "Internet Protocol (IP)," J. Postel, September 1981.

RFC 904   "Exterior Gateway Protocol formal specification," D. Mills,
          April 1984

RFC1112   "Host extensions for IP multicasting," S. Deering, August 1989

RFC 1122  "Requirements for Internet Hosts -- Communication Layers,"
          October 1989

RFC 1123  "Requirements for Internet hosts -- Application and Support,"
          October 1989

RFC 1311  "Introduction to the STD Notes"

RFC 1602  "The Internet Standards Process - Revision 2"

RFC 1661  "The Point-to-Point Protocol (PPP)," W. Simpson, July 1994

   This Internet Draft expires 21 February 1997.

draft-ietf-stdguide-ops-00.txt                                       [Page 11]