wiki:TypicalARTAreaIssues

Typical ART Area Issues

Certain applications-related issues show up time and time again when the Area Directors in the IETF ART Area (or members of the ART Area Review Team) complete reviews of Internet-Drafts. I-D authors are advised to address these issues ahead of time to smooth the path to RFC publication.

(Note: the following list is incomplete; please help us improve it by posting to the art@… discussion list.)

ABNF and BNF

Although the majority of specifications use ABNF (RFC 5234), there are many exceptions. Some older email and web specifications use BNF as specified in RFC 822 (or similar). The latter allows for free insertion of folding whitespaces between different BNF productions. So it is very important to state which version of BNF is used.

Also, please make sure that you check your ABNF using the "BAP" tool at http://tools.ietf.org/tools/bap/abnf.cgi

Base64

Many specifications use Base 64 as defined by RFC 4648, but do not specify which flavor: either "Base 64 Encoding" (Section 4) or "Base 64 Encoding with URL and Filename Safe Alphabet" (Section 5). Also specify what you want done with line-feeds and line lengths. For most modern applications, you SHOULD NOT wrap lines.

Byte Order

In binary protocols, fields longer than 8 bits need to specify byte order. Although network byte order (the most significant byte first) is almost universally used, there are some exceptions, so it is important to spell this out.

Dates and Times

If your specification includes protocol elements with a datatype of "date" or "datetime" or "time", make sure you define the details of its syntax. Even if you reference something like RFC 3339 (which is generally recommended for IETF specifications), make sure that you document all the details about various options, such as use of non-UTC time zones and fractional seconds.

Internationalization

In general, refer to RFC 6365 for helpful discussion about internationalization.

Character Sets

Your spec might have various textual protocol elements, but not explicitly mention the allowable charsets. In IETF protocols, UTF-8 is preferred (along with US-ASCII, which is a subset of UTF-8). See RFC 2277 (BCP 18), Sections 3.1 and 3.2. And see below about Unicode Normalization.

Unicode Normalization

If your spec has protocol elements for usernames, passwords, or identifiers of any kind, please specify how Unicode characters in such fields will be normalized. Visit http://unicode.org/ for details. See (and possibly cite) RFC 5198 for informattion about UTF-8 and normalization. If your character strings might be entered by users and/or might be compared for equality, you will need to consider normalization and canonicalization issues.

Internationalized Domain Names

Your spec might state that a protocol element is a domain name, but ignore the existence of internationalized domain names (IDNs) that include non-ASCII characters. However, IDNs are becoming much more common, so please consult the IDNA documents about the handling of IDNs. The relevant specs are RFC 5890, RFC 5891, RFC 5892, RFC 5893, and RFC 5894. In addition, RFC 5895 (not part of the official IDNA series) might also be relevant to your application.

Language Tags

If your spec has protocol elements that contain human-readable text, you need to specify language tags for those fields, or justify why language tagging is not needed. For details, see RFC 2277 (BCP 18), Section 4.2. Also note that RFC 5646 becomes a Normative Reference when the ability to tag languages is added.

One common approach is to carry the language tag in a separate field (e.g., in XML the "xml:lang" attribute, in ASN.1 by a new field). Such a field can be attached to each element requiring the language tag, or can be global for the whole object/document.

HTTP

New Header Fields

http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-3.1 has advice on how to define new header fields (syntax, interaction with other parts of HTTP like caching, ...)

Passwords

Binary passwords should have a standard way to represent them to users/enter in configuration files (e.g., hex). Text passwords will almost certainly have internationalization issues; see above.

Media Types

First, it's "media type", not "MIME type" or "MIME media type".

If your spec has a protocol element that is defined to contain a media type, make sure you specify if MIME-related parameters are allowed (e.g. 'text/plain' versus 'text/plain;charset=UTF-8').

If your spec defines a new media type registration, you need to follow the process defined in RFC 6838 (also read RFC 2046 for background information). In essence, that means you need to do the following:

  • Submit your actual registration (not a pointer to it) for review on the ietf-types@… discussion list. Do this before you're ready to request publication of your draft.
  • Wait at least two weeks for review comments and make sure you respond to the feedback provided on the list.

Security

Specifications frequently say that a protocol "MUST use TLS for server authentication", but don't specify how the application server identity will be verified. See RFC 6125 for appropriate text and for examples of what other protocols have specified in the past -- or just reference that document (see draft-ietf-sidr-rpki-rtr for a good example of how to profile RFC 6125).

Status / Error Codes

Several application protocols reuse the status codes from RFC 2616, section 6.1.1, then define several other codes that are specific to their protocol. This mechanism works, but has limited semantic extensibility. Instead, consider using the approach from RFC 6120, section 8.3, which acknowledges that new error types will come up in the future, but groups those errors so that unknown errors can get generic processing.

Versioning

Protocol versions happen, so it's usually important to define a version field of some kind. When you do so, specify the requirements on future versions regarding backward compatibility and how this is expressed in the version number (if at all). For example many protocols use "<major>.<minor>" version format, where changes to the <minor> version might mean backward compatible changes. The first two paragraphs from Section 4.4.1 of RFC 3920 provide some text you could re-use.

XML

Formal Descriptions

To formally describe your XML format, you can use either W3 XML Schema or RELAX NG. The IETF does not have a preference between these.

Schema "Gotchas"

XML is, by nature, extensible. If you formally describe your XML format using W3 XML Schema, use the available facilities to declare which elements are extensible and how. For example, use the following constructs:

<xs:anyAttribute namespace="##other" processContents="lax"/>

(Any additional attribute is allowed on the element.)

<xs:any namespace="##other" processContents="lax"/>

(Any additional subordinate element is allowed.)

A good article on this topic is <http://www.pacificspirit.com/Authoring/Compatibility/ProvidingCompatibleSchemaEvolution.html>

W3C XML Schema Part 2 has a helpful chart of built-in datatypes -- consider using the most specific datatypes that describe your elements and attributes.

The boolean datatype has two lexical representations: "true/false" or "1/0". Please make it clear if one representation is preferred, or consider adding a note such as the following:

In accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes, the allowable lexical representations for the xs:boolean datatype are the strings "0" and "false" for the concept 'false' and the strings "1" and "true" for the concept 'true'; implementations MUST support both styles of lexical representation.

An online schema validator is available at the W3C.

Last modified 7 months ago Last modified on Apr 25, 2019, 6:46:41 AM