TOML MIME Type – Free, Online, Private

What .toml is

TOML is a configuration format. Keys and values sit in tables introduced by [table] headers, and arrays of tables use [[table]]. Strings, integers, floats, booleans, datetimes, and arrays are the values. Indentation is not significant, which is the point relative to YAML. Comments start with #. The file is UTF-8. IANA registers application/toml. There is no text/toml you should send. A Cargo.toml or a pyproject.toml on disk has no HTTP type until you serve it. When you do, this is the type.

IANA registers application/toml. The media type is application/toml. Extensions that use it on this page: .toml. A client compares the type, not the filename, once the response has arrived. The filename still matters on disk and in Content-Disposition, which is why a wrong extension and a wrong header are two different bugs.

What sends application/toml

What sends application/toml: Send application/toml; charset=utf-8 when an API or a static host returns a TOML document. A package index that serves a pyproject.toml as text/plain will still be readable and will fail a client that switches on the media type before parsing. Set the registered type. Do not convert TOML to JSON and keep this header. If you convert, send application/json. Datetimes in TOML have a syntax JSON does not share. A client that trusted the header and ran a JSON parser will fail, which is the outcome you want if you mislabeled the body. The file on disk is still .toml. Once the response exists, a client trusts application/toml, not the filename. If you publish configuration that includes secrets, the type is irrelevant to access control. Do not put a private pyproject or a credentials file on a public static host because the extension felt harmless. Cache-Control and authentication decide who can read it.

Content-Type for .toml

Send application/toml; charset=utf-8. The charset parameter names the encoding of the body. Leaving it off forces the client to guess, and for several text types the registered default is not UTF-8. Do not send a charset on a redirect. The header belongs on the response that contains the bytes.

Content-TypeContent-Type: application/toml; charset=utf-8

nginx, Apache, and Express

These snippets map .toml to application/toml. nginx reads the types block when it picks a type from the URL's extension. A location that sets default_type, or an application that sets the header itself, overrides that map. Apache AddType applies in the directory context where you put it. The Express static example writes the header for files ending in .toml so a stale mime database in the framework cannot disagree with the type on this page.

nginx# /etc/nginx/mime.types, inside the types { } block
application/toml            toml;
charset utf-8;
charset_types application/toml;

ApacheAddType application/toml .toml
AddCharset UTF-8 .toml

Expressimport express from "express";

const app = express();
app.use(express.static("public", {
  setHeaders(res, filePath) {
    if (filePath.endsWith(".toml")) {
      res.setHeader("Content-Type", "application/toml; charset=utf-8");
    }
  },
}));

Pitfalls for application/toml

Pitfalls that show up for application/toml, and not for a neighboring type with a similar extension: The sharp edge is a value that looks like a number and is meant as a string, such as a version 1.10 that a careless emitter wrote as a float and rounded. Quote strings. The type will not quote them for you. Another edge is duplicate keys. TOML makes them an error. A merge that concatenates two documents can produce a file that is the right type and invalid. Another is serving a TOML file with a UTF-16 BOM from a Windows editor. Strip it and store UTF-8. A fourth is assuming application/toml implies a particular schema, such as Cargo versus a custom config. The type is the syntax only.

• application/x-toml is unofficial. The registered type is application/toml.
• TOML is not a subset of YAML. Do not run one parser on the other and keep this header.
• Inline tables and dotted keys are syntax. They do not change the media type.
• A .toml URL that returns a 200 HTML page is a broken static mapping, not a TOML document.