In the wild several twtxt users came up with metadata comments in their twtxt files for different purposes. So the Metadata extension is actually not invented at twtxt.net. However, this specification tries to settle on a common standard as extension to the original Twtxt File Format Specification.

Purpose

Twtxt feed authors might want to provide additional information for their feeds or about themselves which clients can pick up and display in a suitable way.

Format

Whenever a physical line in a twtxt file starts with a hash sign (#) it is considered a comment. The comment ends at the end of the line. Comments are usually ignored by twtxt clients and can appear anywhere in a feed. Comments must not be preceded with whitespace.

# this is a comment
### # this one, too

All metadata are part of comments, so they can be easily ignored by clients which do not support metdata.

Metadata are simple key value pairs, they consist of a field name and a field value. Field names and values are separated by an equal sign (=). Each field is on its own physical line. Field names are case insensitive and can contain any number of ASCII letters, digits, minuses and underscores. Whitespace is not allowed as part of the field name. Field names must consist of at least one character.

Field values start after the first equal sign (=) if that follows a valid field name. They are case sensitive and can contain anything, there is no character restriction other than line breaks. Values end at the end of the line. Multiline values must use the Unicode line separator U+2028 just like multiline twts do.

All whitespace around field names and values must be stripped. Both field names and values must not be empty. There must be no more than one hash sign (#) preceding fields. If fields cannot be parsed, they must be ignored and treated as regular comments.

# field-name = field value

It is legal for the same field name to appear more than once. The format allows this, but it doesn’t make sense for all fields. For example, it is reasonable to have many follow fields (one for each feed that a user is following), but you probably won’t find multiple description fields. The order of fields with the same name must be kept so clients can work with them properly.

Valid meta data examples are:

# url = https://example.com/twtxt.txt
#nick=joe
#description =This feed tells about my everyday adventures.

Standardized Fields

This section describes common fields and their purposes.

url

This specifies the URL(s) of the feed. There might be several url fields in a single feed. Feeds may be served over multiple protocols, e.g. HTTPS, HTTP and Gopher. Dedicated url fields advertise the available choices. The first url field value will be used for twt hashing.

Security Considerations

Clients must not automatically change the URL to actually fetch the feed based on this field. However, they might ask the user for confirmation to update the feed URL if they detect that the fetch URL does not match any of the provided url field values.

Automatically updating the feed URL could result in feed spoofing without the user noticing.

nick

This is the feed author’s nick name. When following feeds clients can suggest to go with this nick.

For security reasons clients should not automatically update local nicks without user consent. Otherwise users can be tricked into believing twts are coming from somebody else they’re following. Clients should ask the users when a nick change is detected.

avatar

This specifies the URL for the author’s or feed’s avatar, so it can be displayed along twts, e.g. next to the author. The avatar image is typically in JPEG, PNG or WebP format. Different clients prefer different ratios, so there is no strict rule to follow for feed authors. Often avatars are square.

If the avatar field is missing, it is up to the client how to visually represent the author’s feed. Some clients such as yarnd will automatically generate an avatar based on available data like the feed’s preferred nickname and its URL.

description

The description field contains an explanation what the feed is about. Clients might display this information in a feed details view.

follow

Publicly discloses that the feed author is following another twtxt feed. This can be helpful to aid feed discoverability. The value contains the nick and the URL of the feed separated by whitespace:

# follow = joe https://example.com/twtxt.txt

following

The number of feeds the author is following.

# following = 42

followers

The number of followers this feed has.

# followers = 23

A link to some other resource which is often connected to the feed or author. Similar to follow fields the syntax for link values consists of a link text followed by whitespace and the actual URL. However, the link text can contain whitespace.

# link = Blog https://example.com/blog/
# link = All my source code https://git.example.com/

prev

This field is used by the Archive Feeds Extension.

refresh

This optional field is used by feed authors as a hint to clients to control how often they should fetch or update this feed.

The value of this field is seconds represented by an integer.

NOTE: An empty, bad, or unparsable value is ignored.

Changelog

  • 2021-10-09: Initial version.
  • 2021-10-31: Clarify that metadata field values must not be empty.
  • 2021-12-26: Clarify that clients must not automatically change the feed URL to fetch the feed based on url metadata field values.
  • 2021-12-29: Add new refresh metadata field to hint to clients how often a feed can or should be fetched.