The Restatement Anti-Pattern

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

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 inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 3 September 2024.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶

Table of Contents

1. Introduction

Normative documents that cite other normative documents often restate normative content extracted out of the cited document in their own words.¶

The present memo explains why this can be an Antipattern [KOENIG][ANTIPATTERN], and how it can be mitigated.¶

2. The Restatement Anti-Pattern

A Restatement is the attempted expression of information that is already expressed elsewhere.¶

In this document, we are mostly concerned with Normative Restatements, i.e., statements that are intended (or look like they are intended!) to be normative.¶

Restatements are rarely verbatim copies of the original statement and the context needed to interpret that, so they tend to introduce uncertainty about the interpretation of the restatement.¶

Authors often presume a reader is well-versed enough to infer that such an uncertainty (or outright contradiction) is not intended and how it is to be resolved. There is little reason to believe this is actually the case.¶

An internal restatement is a restatement of information that has been provided previously in the document under discussion. Note that an unambiguous internal reference is not a restatement, as it points to the original text and its context. (There may still be uncertainties how to interpret the internal restatement in the additional context.)¶

A reference is unambiguous if the previous passage is clearly identified and delimited.¶

An external restatement is a restatement of information that has been provided in (one or more) external documents. Here there is increased danger of an unclear scope of the reference, often by pointing to an entire document where only a specific passage is actually intended to be referenced.¶

Restatements can be entirely hidden, i.e., there is no indication that information given is a restatement. Restatements can also be explicit by clearly being identified as such, typically no longer using normative language.¶

Restatements can be an Anti-Pattern because they can be "a common response to a recurring problem that is usually ineffective and risks being highly counterproductive" [WP-ANTIPATTERN]. Section 3 discusses the recurring problems as perceived by document authors, Section 4 explains why restatements can be ineffective and counterproductive, and Section 5 discusses how to use restatements in a way that is not.¶

3. Reasons for making restatements

There are many reasons that cause document authors to include restatements in their work, many of which are actually good reasons once the perils of restatements are properly managed.¶

4. Perils of restatements

The danger of restatements is that they might not be exactly expressing the same normative statement that the cited document makes.¶

One form of this is the incomplete restatement.¶

Abridged copies of a normative statement from the cited document often leave open whether the abridgment is intentional: Is the referencing document only importing some of the requirements of the cited document? In the worst case, the restatement may appear to be forking an ecosystem, i.e., an implementation of the cited document cannot be used because it makes additional constraints that are not meant to be included in the referencing document. (This peril of course is also present with intentional changes to the normative statements in a cited document, but is likely to receive much more attention during review.)¶

Section 6.5 presents an example for the situation where a reader might infer behavior based on the common law statute interpretation rule:¶

• "Expressio unius est exclusio alterius"¶

which states that the reader is to presume that expressly referencing one matter implies that other similar matters are intentionally not mentioned and therefore are excluded. This is particularly problematic with abridged statements, where this rule may be invoked by the reader without an author being aware of it.¶

Restatements may be slightly semantically different from the cited document, in particular if the latter is based on a relatively inaccessible (possibly poorly documented or poorly developed) terminology. Both authors and readers may not be aware that they need to use tools that are commonplace in the ecosystem of the cited document.¶

A large danger originates from restatements that are unclear whether a new normative requirement is intended or a just a restatement of known normative requirements of the cited document. This is, of course, particularly dangerous for hidden restatements.¶

A restatement can cause maintainability hazards, as illustrated in Section 6.1; it also can cause a referencing document to decouple from the ecosystem of a cited document once that is repaired (Section 6.3).¶

Finally, to readers familiar with the cited document, the restatement can be surprising; if there really is no information in the restatement, the reader automatically searches for a specific reason this restatement is made and starts to reinterpret it until it means something specific that would justify its presence. If the restatement is not clearly identified as such, this is likely to cause misinterpretations, as if the usage envisioned attempts to fork the cited ecosystem. (Often, the people who need to interpret the document in question are actually more familiar with the cited document and the surrounding ecosystem than the authors of the referencing document, who may just be pulling in the ecosystem to solve one of their problems.)¶

5. Defusing restatements

A general recommendation for readers of a referencing document is that they should try to detect restatements and read them in full knowledge of their perils (Section 4). If a resolution is required, the RFC errata process may provide a (poor) mechanism to obtain the resolution and ensure it is documented in the context of the referencing document. Mailing list discussions are also a good way to obtain a resolution, but for additional readers they can be hard to find, and, when found, it can be hard to extract any consensus that was formed.¶

The rest of this section provides a summary of the recommendations made by this document, employing RFC2119 keywords as an instruction to the potential implementers of this document, i.e., document authors and reviewers.¶

Much of the danger of restatements can be averted if they are sufficiently identified by the authors as such.¶

• For identification of internal restatements, use phrases such as: In other words, hence, in particular, as discussed in Section NN.¶

• For identification of external restatements: As described/defined in …, as per …¶

• In both cases, make sure that any local reference is clear and any non-local reference is resolvable and well-scoped.¶

• Rephrasing the statement as a Note can make clear that there is no normative intention.¶

• Examples MUST be identified clearly as such, including identifying any explanatory notes as such so that these are not misunderstood as new normative statements.¶

If a larger copy from a cited document is made, it SHOULD be made verbatim and differences introduced deliberately should be explicitly identified, possibly in a second step. Note that the FDT mechanisms and their evolution can make verbatim copies less useful, in which case a systematic approach of first copying and fixing and then, if necessary, modifying can help the reader. For instance, [RFC2397] uses a variant form of ABNF that can be parsed only once the variant ":=" syntax is replaced by "=". (This is an active specification and was cited as recently as in Section 4.3 of [RFC9399], which provides a clearly identified restatement in modern ABNF, with errata applied and rules referenced from elsewhere added [we ignore the innocuous redefinition of "hex" from "HEXDIG"].)¶

By making the copy informative, repairs from the base document (in the [RFC2397] example e.g. [errata2397]) can be imported, even future ones.¶

Where the copy is made because the cited document is not openly available, this also often requires more processing than a verbatim copy, increasing the probability of introducing errors and misunderstandings. This can be somewhat mitigated by clearly stating the purpose of a restatement, and the intended result when the restatement and the original diverge.¶

6. Examples

link-extension = parmname [ "=" ( ptoken / quoted-string ) ]

link-param  = ( "rel" "=" relation-types )
            / ( "anchor" "=" <"> URI-Reference <"> )
            / ( "rev" "=" relation-types )
            / ( "hreflang" "=" Language-Tag )
            / ( "media" "=" ( MediaDesc / ( <"> MediaDesc <"> ) ) )
            / ( "title" "=" quoted-string )
            / ( "type" "=" ( media-type / quoted-mt ) )

link-param     = ( "rel" "=" relation-types )  ; ...
               / ( "type" "=" ( media-type / quoted-mt ) )
               / ( "rt" "=" relation-types )
               / ( "if" "=" relation-types )
               / ( "sz" "=" cardinal )
cardinal       = "0" / ( %x31-39 *DIGIT )

7. Security Considerations

Restatements about security requirements and properties can create the same uncertainties and interoperability problems as restatements in other contexts. Security considerations sections have turned out to be an attractor for such problems. They are meant "both to encourage document authors to consider security in their designs and to inform the reader of relevant security issues" (Section 1 of [RFC3552]). In practice, they tend to be the first point in a document that security issues are considered at all, so they often both contain normative statements that are nowhere else in the document and security-conscious restatements of other normative statements in the document, the latter with all the perils that this memo is about. The fact that security considerations sections are often heavily fleshed out during IESG processing can exacerbate the problem.¶

8. IANA Considerations

This document has no IANA actions.¶

Acknowledgments

Julian Reschke opened the author's eyes to the fundamental problem of restatements, possibly not using this word. Many IETFers over decades have worked on mitigating restatements; the author apologizes that examples in this memo naturally mainly come from the author's own recollection.¶

Author's Address