Stream Draft Content Guidelines

This page explains how to write a Stream draft in The Gathering template format. It covers draft naming, front matter fields, and reference sections.

For process context, see Stream-Drafts and The Gathering Process.

Name your draft file and docname

Use an IETF-style component model for Stream draft names and keep docname aligned with the filename (without .md).

  • Individual-style: draft-<author>-<subject>.md
  • Group-targeted style: draft-<author>-<group>-<subject>.md
  • Allowed characters: lowercase a-z, digits 0-9, and hyphen -.
filename: draft-author-mx-req-lang.md
docname: draft-author-mx-req-lang

Important: In The Gathering workflow, versioning is attached at release time (for example -00, -01) rather than in the source markdown filename.

Template front matter (starting point)

Start from the exact front matter shape in draft-todo-author-stream.md:

---
title: "TODO - Your title"
abbrev: "TODO - Abbreviation"

docname: draft-todo-author-stream
date:
consensus: false
keyword:
  - mx
  - stream
  - draft
author:
  -
    fullname: Your Name Here
    organization: Your Organization Here
    email: your.email@example.com
    address: Your Address
normative:
  MX-0001:
informative:
  Example-Spec:
    title: "Example Supporting Specification"
    author:
      -
        organization: Example Working Group
    date: 2026-01
    target: https://example.org/spec
---

Fields

  • title: Full document title shown in rendered output.
  • abbrev: Short subtitle under the title.
  • docname: Stable identifier; keep it equal to markdown filename base.
  • date: Draft date for the current editor copy (recommended YYYY-MM-DD).
  • consensus: Process state flag (true or false).
  • keyword: Discovery tags listed as YAML array items.
  • author: YAML list of author objects.
  • normative: References required to implement or interpret the draft.
  • informative: Supporting or background references.

Each author is one YAML object under author:. Current supported subfields are:

  • fullname: Display name in author sections and metadata.
  • organization: Affiliation.
  • email: Contact email.
  • address: Postal/location text line.

Single author example

author:
  -
    fullname: Alex Doe
    organization: Example Lab
    email: alex@example.org
    address: London, UK

Multiple authors example

author:
  -
    fullname: Alex Doe
    organization: Example Lab
    email: alex@example.org
    address: London, UK
  -
    fullname: Sam Lee
    organization: Open Systems Group
    email: sam@example.org
    address: New York, US

Keep indentation exactly like the template (hyphen on its own line under author:). This avoids parser issues and keeps rendered output correct.

Use stable reference IDs under normative and informative. IDs are keys such as MX-0001 or W3C-DID-CORE.

Minimal reference placeholder

normative:
  MX-0001:

Informative reference with full metadata

normative:
  MX-0001:

informative:
  W3C-DID-CORE:
    title: "Decentralized Identifiers (DIDs) v1.0"
    author:
      -
        organization: W3C
    date: 2022-07
    target: https://www.w3.org/TR/did-core/

Multiple references example

normative:
  MX-0001:
  MX-0002:

informative:
  Example-Spec:
    title: "Example Supporting Specification"
    author:
      -
        organization: Example Working Group
    date: 2026-01
    target: https://example.org/spec
  W3C-DID-CORE:
    title: "Decentralized Identifiers (DIDs) v1.0"
    author:
      -
        organization: W3C
    date: 2022-07
    target: https://www.w3.org/TR/did-core/

In current rendering, reference author entries use organization values for display.

Body structure markers

Use section markers exactly as shown: --- abstract, --- middle, --- back.

--- abstract
One-paragraph summary.

--- middle
# Introduction
# Conventions and Definitions
# Main Body
# Security Considerations

--- back
# Acknowledgments

Important: Status of This Memo and Copyright Notice are added automatically by the build/render pipeline. Do not add those sections manually in draft source content.

Full example

Complete template example with front matter, abstract, middle, and back sections:

Important: This full example intentionally excludes Status of This Memo and Copyright Notice because they are appended automatically at render time.

---
title: "TODO - Your title"
abbrev: "TODO - Abbreviation"

docname: draft-todo-author-stream
date:
consensus: false
keyword:
  - mx
  - stream
  - draft
author:
  -
    fullname: Your Name Here
    organization: Your Organization Here
    email: your.email@example.com
    address: Your Address
normative:
  MX-0001:
informative:
  Example-Spec:
    title: "Example Supporting Specification"
    author:
      -
        organization: Example Working Group
    date: 2026-01
    target: https://example.org/spec

--- abstract

TODO Abstract

--- middle

# Introduction

TODO Introduction.

# Conventions and Definitions

TODO Conventions and Definitions.

# Main Body

TODO Main Body.

# Security Considerations

This document has no direct security considerations.

--- back

# Acknowledgments

TODO acknowledge.