xml2rfc FAQ January 2022
Russo Informational [Page]
A. Russo
RFC Production Center

xml2rfc Frequently Asked Questions


This is a list of frequently asked questions regarding xml2rfc, a tool that can be used to create Internet-Drafts or RFCs.

This FAQ is for version 3 of xml2rfc; the vocabulary has been changed significantly from version 2. For guidance on version 2, please see the FAQ for xml2rfc v2.


This document has been replaced by https://authors.ietf.org.

Table of Contents

1. The Basics

1.1. What is xml2rfc?

xml2rfc is a tool that lets you convert an XML source file into a text, HTML, PDF, expanded XML file, or various other options. It is available as a web-based service (https://author-tools.ietf.org/) or for download (https://pypi.org/project/xml2rfc/. Version 3 of the tool adds new features and is used by the RFC Editor to create RFCs.

1.2. Why should I use xml2rfc?

It's an easy way to create an Internet-Draft in the proper format. It handles boilerplate text and reference text. The HTML and PDF output formats have new features (such as including SVG figures and non-ASCII characters), and the source file can be used for metadata extraction. Also, the RFC Editor will make use of your source file. (For background, see the RFC Format FAQ.)

1.3. How much XML do I need to know?

You need the essentials. XML uses start and end tags, which are nested and matching, and they are case-sensitive. See "XML basics" in Writing I-Ds and RFCs using XML (revised) for more details.

1.4. Where can I get more information?

2. Creating a Draft

You have several choices when getting started with xml2rfc, such as:

There are also tools available to let you edit non-XML source and then compile it to xml2rfc XML:

If you intend to host your draft in git or on Github, see https://ietf-gitwg.github.io/ for advice.

2.2. Where can I get a template?

There is a v3 template available here: https://tools.ietf.org/tools/templates/draft-davies-template-bare-07.xml. In addition, several templates for xml2rfc v2 are available from https://tools.ietf.org/tools/templates [templates]. They include templates for a generic draft (e.g., draft-davies-template-bare.xml), as well as for a draft containing a MIB module (e.g., mib-doc-template-xml.txt).

2.3. How can I do it without a template?

You can convert an existing XML file from the v2 vocabulary to the v3 vocabulary using xml2rfc --v2v3 (see Section 7.1), and go from there. Use <t> elements for paragraphs, and <figure><artwork> elements for figures. Use <![CDATA[ ... ]]> within <sourcecode> or <artwork> elements that contain the less than character (<). (See What is CDATA for? for more information.)

To get a citation like "[RFC2119]", use <xref target="RFC2119"/>. See Using References for more information.

2.4. How do I use the rfc element to create an Internet-Draft?

Use the category attribute to indicate the intended category of your draft, where std is Standards Track, info is Informational, exp is Experimental, bcp is Best Current Practice, and historic is Historic.

Use the submissionType attribute to indicate the intended document stream, where the value can be IETF, IAB, IRTF, or independent.

See Appendix A.1 of [RFC7991] for information about the ipr attribute.

Use the docName attribute to indicate the filename.

If the document potentially updates or obsoletes any RFCs, use the updates and obsoletes attributes to indicate the relevant RFC numbers. For Internet-Drafts, this information will be displayed in the header, followed by "(if approved)".

For example, putting it together:

   updates="1234, 1235"

Note: The attributes number and seriesNo will be added by the RFC Editor if your draft is approved for publication as an RFC.

Note: Some features that used to be processing instructions (in v2) are now attributes of the rfc element (in v3) -- for example, sortRefs and symRefs.

3. Using References

3.1. How do I put in a reference?

A set of online citation libraries are maintained on xml2rfc.tools.ietf.org [xml2rfc]. They include citations for RFCs, Internet-Drafts, and documents produced by the W3C and 3GPP, among others.

To make use of the citation libraries, use an xi:include in the references section as follows.


For an Internet-Draft, the citation filename uses the draft string. For example:


Preferably, use the citation libraries when possible. However, another option is to include the complete reference element (see Section 3.2). Here's a template of a reference element:

    <reference anchor="" target="">
            <author initials="" surname="" fullname="">
                <organization />
            <date month="" year="" />
        <seriesInfo name="" value="" />

All are cited textually in the same manner -- by using xref elements where the target corresponds to the anchor of the reference element, e.g., <xref target="RFC2119" />. The anchors for RFCs are "RFCNNNN" (4 digits, using leading zeros) and the anchors for Internet-Drafts are "I-D.<name without "draft-" or the version number>".

3.2. How do I insert the full reference?

There are several ways to insert the full reference element from the citation library:

  1. Keep a local copy of the citation libraries. They are available from https://xml2rfc.tools.ietf.org [xml2rfc].
  2. Use a browser to look it up online, e.g., https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml, and copy the page source.
  3. Run xml2rfc with output mode set to XML. The output will include the complete reference elements for any entities and includes.

3.3. How do I change the reference tags from symbolic to numeric, i.e., from [RFC2119] to [1]?

In the rfc element, set the attribute symRefs="no" for symbolic references. This makes reference tags be numeric, e.g., [1], instead of symbolic, e.g., [RFC2119].

3.4. How do I make the reference tag [IKEv2] instead of [RFC4306]?

Use the displayreference element and set the to attribute to the nickname. Tip: place it before the first references element. For example:

<displayreference target="RFC7296" to="IKEv2"/>


Kaufman, C., Hoffman, P., Nir, Y., Eronen, P., and T. Kivinen, "Internet Key Exchange Protocol Version 2 (IKEv2)", STD 79, RFC 7296, DOI 10.17487/RFC7296, October 2014, <https://www.rfc-editor.org/info/rfc7296>.

3.5. How do I get the references listed in alphabetical order?

In the rfc element, set the attribute sortRefs="yes". Note that sortRefs only has an effect if symRefs="yes".

3.6. How do I reference a URL?

The eref element for an external reference creates a link in the HTML output. For example:

<eref target="https://www.w3.org">

yields https://www.w3.org.

<eref target="https://www.w3.org">W3C Home Page</eref>

yields W3C Home Page.

Another option is using xref and creating a reference that uses the target attribute for the URL. For example:

    <reference anchor="W3C" target="https://www.w3.org/">
            <title>World Wide Web Consortium (W3C)</title>


[W3C]     "World Wide Web Consortium (W3C)", <https://www.w3.org/>.

3.7. How do I get two sections of references: Normative and Informative References?

Use the name element (child of the references element) as follows:

        <name>Normative References</name>
        <name>Informative References</name>

3.8. How do I create a reference to a BCP (or STD) that contains multiple RFCs?

Use <referencegroup> with an xi:include for each RFC inside of it:

<referencegroup anchor="STD78" target="https://www.rfc-editor.org/info/std78">

which yields

  [STD78]    Schoenwaelder, J., "Simple Network Management Protocol
             (SNMP) Context EngineID Discovery", STD 78, RFC 5343,
             September 2008.

             Harrington, D. and J. Schoenwaelder, "Transport Subsystem
             for the Simple Network Management Protocol (SNMP)",
             STD 78, RFC 5590, June 2009.

             Harrington, D. and W. Hardaker, "Transport Security Model
             for the Simple Network Management Protocol (SNMP)",
             STD 78, RFC 5591, June 2009.

             Hardaker, W., "Transport Layer Security (TLS) Transport
             Model for the Simple Network Management Protocol (SNMP)",
             STD 78, RFC 6353, July 2011.


3.9. How do I make a cross-reference to another section?

Make sure the section you want to reference has an anchor attribute. For example:

   <section anchor="s_using_lists">

Then, refer to it with an <xref> element:

  See <xref target="s_using_lists" />.

which yields

See Section 4.

(where the number of that section is determined dynamically).

Use <xref> with the format attribute. For example, assuming the anchors for the relevant sections match the targets:

See Sections <xref target="s_using_refs" format="counter" /> and
<xref target="s_using_lists" format="counter" />.

yields the output:

See Sections 3 and 4.

Note: The format attribute can have the value "title", which displays the title of the section. For example,

See Sections <xref target="s_using_refs" format="title" /> and
<xref target="s_using_lists" format="title" />.

yields the output:

See Using References and Using Lists.

Use <xref> with sectionFormat="bare". For example:

See Sections <xref target="RFC3550" section="5" sectionFormat="bare" /> and
<xref target="RFC3550" section="6" sectionFormat="bare" /> in
<xref target="RFC3550"/>.

yields the output:

See Sections 5 and 6 in [RFC3550].

4. Using Lists

4.1. How do I get different kinds of lists?

For bulleted lists, use the <ul> element.

For an empty list (indentation only), use the <ul> element with empty="true".

For definition lists (a.k.a. hanging lists in xml2rfc v2), use the <dl> element. See Section 4.4.

For numbers or letters, use the type attribute of the <ol> element; examples below.

For full details, see Section 2.34.5 of [RFC7991] and the schema documentation.

  • type="1" --> 1, 2, 3, ...
  • type="I" --> I, II, III, ...
  • type="i" --> i, ii, iii, ...
  • type="a" --> a, b, c, ...
  • type="A" --> A, B, C, ...
  • type="REQ%d:" --> [See Section 4.2.]

4.2. How do I get a list like (1), (2), (3) or (a), (b), (c)?

(2)    is   <ol type="(%d)">

(b)    is   <ol type="(%c)">

REQ2:  is   <ol type="REQ%d:">

4.3. How do I get continuous numbering in a list that is split by text (or across sections)?

Set the group attribute to the same value for each <ol> element. For example:

 <ol type="REQ%d:" group="reqs">
  <li>do a</li>
  <li>do b</li>
<t>Here is text in between.</t>
<ol type="REQ%d:" group="reqs">
  <li>do c</li>
  <li>do d</li>
<t>Here is more text in between.</t>
<ol type="REQ%d:" group="reqs">
  <li>do e</li>
  <li>do f</li>


do a
do b

Here is text in between.

do c
do d

Here is more text in between.

do e
do f

4.4. How do I get indentation? or How do I use definition lists?

Use a <dl> element (definition list), where each <dt> (term) in has a corresponding <dd> (description).

For example:

  <dd>Unused and available for assignment via
  documented procedures.</dd>

  <dd>Not to be assigned.  Reserved values are
  held for special uses, such as to extend the namespace
  when it become exhausted.  Reserved values are not
  available for general assignment.</dd>


Unused and available for assignment via documented procedures.
Not to be assigned. Reserved values are held for special uses, such as to extend the namespace when it become exhausted. Reserved values are not available for general assignment.

Note: The appearance is slightly different in the text output.

Use newline="true" to get a line break after the term. For example:

<dl newline="true">
  <dd>Unused and available for assignment via
  documented procedures.</dd>

  <dd>Not to be assigned.  Reserved values are
  held for special uses, such as to extend the namespace
  when it become exhausted.  Reserved values are not
  available for general assignment.</dd>


Unused and available for assignment via documented procedures.
Not to be assigned. Reserved values are held for special uses, such as to extend the namespace when it become exhausted. Reserved values are not available for general assignment.

4.5. How do I create nested lists?

The key is that any text before or after the inner list must be in a <t> element.

Example: <ol> nested within <dl>

 <dt>Foo validator:</dt>
    <t>It performs the following actions:</t>
    <ol type="1" spacing="compact">


Foo validator:

It performs the following actions:

  1. runs
  2. jumps
  3. walks

Example: <ul> nested within <ol>

<ol type="Step %d:">
 <li><t>Send it to</t>
    <ul spacing="compact">


Step 1:

Send it to:

5. The Finer Points

5.1. What is CDATA for?

A CDATA block is left alone by xml2rfc. It does not try to parse XML inside of a CDATA block. (For example, if a figure contains "<", you don't have to use &lt;) So it is especially good for when there are XML examples in the document.

5.2. What are the entities used for special characters?

To prevent these characters from being parsed as XML, use

&amp; for &
&lt; for <
&gt; for >

In addition, the following entities are defined:

&nbsp; for non-breaking space
&nbhy; for non-breaking hyphen
&wj; for word joiner

5.3. How do I indicate the editor of the document?

Use the role attribute of the author element. For example:

<author initials="J" surname="Doe" fullname="John Doe" role="editor">

5.4. How do I list the contributors or include acknowledgments?

In a "Contributors" section, you can use the <contact> element, which has the same structure as the <author> element. Including address information is optional.

In an "Acknowledgments" section, you can use the <contact> element within <t> to list inviduals' names (typically without address information).

5.5. How do I insert questions for my coauthors?

You can use comments <!-- --> or <cref> elements. Comments are only visible in the XML source file.

Example of using comments:

<!-- [JD] This point needs revision.-->

<cref> will show up in the output when the attribute display="true" (which is the default).

Example of using <cref>:

<cref anchor="Q1" source="JD">This point needs revision.</cref>


This point needs revision.JD

6. Miscellaneous

6.1. How do I know if my XML is valid?

xml2rfc validates it. Also, you can run rfclint: https://pypi.org/project/rfclint/.

6.2. Can I get a different kind of HTML output?

Yes, rfc2629.xslt by Julian Reschke provides a different kind of HTML output than the HTML output mode of xml2rfc. See "Transforming RFC7749-formatted XML through XSLT" for more information.

6.3. Is there a tool that will turn my text file into an XML file (i.e., id2xml)?

Yes, id2xml is available here: https://pypi.org/project/id2xml/. It is available as a web service on https://xml2rfc.tools.ietf.org/.

7. New with v3

7.1. How do I convert my XML file from v2 to v3 so I can make use of the new features?

On the command line: xml2rfc --v2v3 inputfile.xml. You can use the --add-xinclude option to replace RFC and I-D reference elements with the appropriate xi:include element.

Or, using the web service (https://xml2rfc.tools.ietf.org/experimental.html), select "Output format: convert v2 to v3 XML".

After converting it to v3, please see Section 7.2.

7.2. After converting an XML file from v2 to v3, what further updates might be needed for the v3 XML file?

You may want to do the following (for the sake of generating good output and having a semantically accurate XML file):

  • Review each list.

    • Is it really a list? Or should indentation be added in another manner, e.g., <blockquote>.
    • If so, should it be <dl>, <ul>, or <ol>? See Section 4.
  • Review each <artwork>.

  • Search for URLs; should these be <eref>? See Section 3.6.
  • Look for equations or other text where new features may improve clarity. See Section 7.4.
  • Search for hardcoded citation tags (e.g., [RFC5234]) and update to <xref>s. See Section 3.1.
  • Search for "section" and make a link for any section number in RFCs and I-Ds (using <xref> with section and sectionFormat attributes). See Section 3.10.
  • Review postal addresses of authors; has each address been tagged correctly?

7.3. How do I fix common errors after the upgrade from v2 to v3?

xml2rfc warns "Setting consensus="true" for IETF STD document".
This is being discussed on the xml2rfc-dev list. You should disregard this warning for now.
xml2rfc fails with "Reserved anchor name: section-.... Don't use anchor names beginning with one of u-, section-, iref-, figure-, table-".
Rename your section.

Other errors can appear if you're using a helper tool to write your XML:

7.3.1. kramdown-rfc2629

If you're using kramdown-rfc2629:

If you don't specify a date for a reference, xml2rfc fails with "Expected <date> attribute "year" to be an integer, but found "n.d.""
This issue is tracked in https://github.com/cabo/kramdown-rfc2629/issues/64. Add date: false to your reference to avoid the error.

7.3.2. i-d-template

If you're using i-d-template:

xml2rfc warns that "The 'docName' attribute of the <rfc/> element should have a revision number as the last component: docName="draft-foo-bar-02"."
This issue is tracked in https://trac.ietf.org/tools/xml2rfc/trac/ticket/439. You can't modify your source to avoid it.

7.4. What are the new features with v3?

Some highlights are including Unicode characters, text formatting, and SVG diagrams. For complete details, see Section 1.3 of [RFC7991].

7.5. How do I insert non-ASCII characters?

With encoding="utf-8" in your XML file, you can use non-ASCII characters in the following locations:

  • <author> element (using the fullname, initials, and surname attributes, while the asciiFullname, asciiInitials, and asciiSurname attributes hold the ASCII equivalents)
  • <organization> element
  • author's postal address (using <street>, <city>, <region>, <code>, and <country> elements) and email address. Each of these elements has an ascii attribute to hold the ASCII equivalent, which will also appear in the output format.
  • <contact> element (same structure as for the <author> element)
  • contact's postal address and email address (same structure as for the <author> element)
  • body of the document

    • by using the <u> element; see examples below, or
    • directly in <sourcecode> or <artwork> elements (without the <u> element)

The <u> element goes around a Unicode character; set the format attribute (using the keywords num, name, lit, char, and ascii) to indicate what is rendered in the output. See the schema documentation.

Below are examples of using

<u format="num-lit">水</u>

and various other options for the format attribute.

a single character U+6C34 ("水"), often representing "water"
a single character U+6C34 (CJK UNIFIED IDEOGRAPH-6C34), often representing "water"
a single character U+6C34 ("水", CJK UNIFIED IDEOGRAPH-6C34), often representing "water"
a single character U+6C34 (CJK UNIFIED IDEOGRAPH-6C34, "水"), often representing "water"
a single character CJK UNIFIED IDEOGRAPH-6C34 ("水", U+6C34), often representing "water"
format="lit-name-num" (default):
a single character "水" (CJK UNIFIED IDEOGRAPH-6C34, U+6C34), often representing "water"
format="{lit} character ({num})":
the "水" character (U+6C34), often representing "water"

For background, see [RFC7997].

7.6. How do I insert a table?

For example:

<table anchor="table_ex">
  <name>IETF Meetings in 2005</name>
      <th align='center'>IETF #</th>
      <th align='center'>City</th>
      <th align='center'># of Attendees</th>
      <td align="center">62</td>
      <td align="center">Minneapolis</td>
      <td align="center">1133</td>
      <td align="center">63</td>
      <td align="center">Paris</td>
      <td align="center">1450</td>
      <td align="center">64</td>
      <td align="center">Vancouver</td>
      <td align="center">1240</td>


Table 1: IETF Meetings in 2005
IETF # City # of Attendees
62 Minneapolis 1133
63 Paris 1450
64 Vancouver 1240

Data from https://www.ietf.org/how/meetings/past/.

For full details, see Section 2.54 of [RFC7991].

7.7. How do I generate SVG that will be accepted in an RFC?

You can check your SVG file against the SVG Tiny 1.2 spec on the experimental page (https://xml2rfc.tools.ietf.org/experimental.html), and a script called svgcheck is available here: https://pypi.org/project/svgcheck/.

For more information, see [RFC7996] and Tips on creating SVG files.

7.8. How do I include SVG in my document?

From RFC 7991:

There are at least five ways to include SVG in artwork in Internet-Drafts:

  • Inline, by including all of the SVG in the content of the element, such as: <artwork type="svg"><svg xmlns="http://www.w3.org/2000/ svg...">
  • Inline, but using XInclude (see Appendix B.1), such as: <artwork type="svg"><xi:include href=...>
  • As a data: URI, such as: <artwork type="svg" src="data:image/ svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3...">
  • As a URI to an external entity, such as: <artwork type="svg" src="http://www.example.com/...">
  • As a local file, such as: <artwork type="svg" src="diagram12.svg">

For any given SVG artwork, you can provide an ASCII art equivalent (for use in the text output) by using the <artset> element. For example:

  <name>TCP Header Format</name>
    <artwork alt="TCP Header" type="svg"
    <artwork alt="TCP Header from RFC 793" type="ascii-art">
       [... ASCII ART ...]

which yields:

TCP Header 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 Source Port Destination Port 0 Sequence Number 8 Acknowledgement Number 16 Data Offset Reserved Urg Ack Psh Rst Syn Fin Window 24 Checksum Urgent Pointer 32 Options Padding 40 Data 48
Figure 1: TCP Header Format

7.9. How do I get bold, italics, or a fixed-width font?


  • <em> for italics,
  • <strong> for bold, and
  • <tt> for fixed-width font.

7.10. How do I get subscript and superscript?

Use <sub> for subscript and <sup> for superscript.

Example (using text from RFC 6330):

  • x0 = (y + i) mod 28
  • x1 = (floor(y / 28) + i) mod 28
  • x2 = (floor(y / 216) + i) mod 28
  • x3 = (floor(y / 224) + i) mod 28

7.12. How should a YANG module appear?

For a YANG module, please use <sourcecode> with type="yang" and markers="true". The latter creates the <CODE BEGINS> and <CODE ENDS> tags in the output. If you set the name attribute, the filename will appear in the output. For example:

<sourcecode type="yang" markers="true" name="foo.yang">


<CODE BEGINS> file "foo.yang"

7.15. How do I download the XML source files for all RFCs?

The source files of RFCs have changed over time. Most RFCs have NROFF source files; sometimes an XML file has been archived. You can request an XML source file directly from rfc-editor@rfc-editor.org. For RFCs created after the transition to xml2rfc v3, the XML files will be available for bulk download from https://www.rfc-editor.org/retrieve/bulk.

8. Informative References

Rose, M., "Writing I-Ds and RFCs using XML (revised)", , <https://xml2rfc.ietf.org/authoring/draft-mrose-writing-rfcs.html>.
Levkowetz, H., "Implementation notes for RFC7991,", Work in Progress, Internet-Draft, draft-levkowetz-xml2rfc-v3-implementation-notes-13, , <https://datatracker.ietf.org/doc/html/draft-levkowetz-xml2rfc-v3-implementation-notes-13>.
Kaufman, C., Hoffman, P., Nir, Y., Eronen, P., and T. Kivinen, "Internet Key Exchange Protocol Version 2 (IKEv2)", STD 79, RFC 7296, DOI 10.17487/RFC7296, , <https://www.rfc-editor.org/info/rfc7296>.
Schulzrinne, H., Casner, S., Frederick, R., and V. Jacobson, "RTP: A Transport Protocol for Real-Time Applications", STD 64, RFC 3550, DOI 10.17487/RFC3550, , <https://www.rfc-editor.org/info/rfc3550>.
Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, , <https://tools.ietf.org/html/rfc7991>.
Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", RFC 7996, DOI 10.17487/RFC7996, , <https://www.rfc-editor.org/info/rfc7996>.
Flanagan, H., Ed., "The Use of Non-ASCII Characters in RFCs", RFC 7997, DOI 10.17487/RFC7997, , <https://www.rfc-editor.org/info/rfc7997>.
"Templates directory", <https://tools.ietf.org/tools/templates/>.
"World Wide Web Consortium (W3C)", <https://www.w3.org/>.
"xml2rfc", <https://author-tools.ietf.org/>.


This FAQ was made possible by the tools, documentation, and test files created by Henrik Levkowetz, Julian Reschke, Paul Hoffman, and Sandy Ginoza. Also, thanks to Jeffrey Yaskin for contributing.

Author's Address

Alice Russo
RFC Production Center