Mapping filename extensions to MIME types

Content Types

Preliminaries

This note describes how to map filename extensions to MIME-types to declare which filename extensions are used by the server and what their inner contents contain.

Mapping filename extensions to content-types is a required part of server configuration. Industry-wide best practices for filename extensions are a good start, but there are too many possibilities to cover every scenario. Consider, by way of example, simple.scss, simple.mjs, and simple.svg — only a site's webmaster would know for sure what is in these files and how to serve them. When configuring the server, the content-types section is used to associate filename extensions with content-type HTTP headers.

File formats are identified using media-types, also known as MIME types or content-types. These are described in IETF RFC 6838 Media Type Specifications and Registration Procedures.

Configuration

The content-types configuration section is used to associate filename extensions to content-types. It comprises a collection of two-part entries: the left hand side is the filename extension (without a leading dot), and the right-hand side is the MIME-type. Filename extensions are case-sensitive.

When a requested file is found on the server, but no content-type is associated with its extension, no content-type header is sent with the response, per HTTP official guidelines.

It is possible that more than one filename extension is used for the same MIME-type. When this occurs, each filename extension should be declared and mapped as a separate configuration entity.

Placement

The content-types section may appear in either the server section or a host section. When values occur in both the server and host sections, they are merged according to the standard rules defined for the merge attribute.

EBNF

SP ::= U+20
CR ::= U+0D
SOLIDUS ::= U+2F
ASTERISK ::= U+2A
LEFT-CURLY-BRACKET ::= U+7B
RIGHT-CURLY-BRACKET ::= U+7D
media-type ::= 'text' | 'application' | 'image' | 'audio' | 'video' | 'multipart'
subtype ::= (ALPHA | DIGIT | )*
MIME-type ::= media-type SOLIDUS subtype
filename-extension ::= (ALPHA | DIGIT | ††)*
content-type-entry ::= filename-extension SP MIME-type CR
content-types-section ::= 'content-types' SP LEFT-CURLY-BRACKET CR
content-type-entry*
RIGHT-CURLY-BRACKET CR

† See section 4.2 of RFC 6838 for exact rules

†† Legal file system characters vary by platform

Cookbook

Example 1: Filename extensions associated with MIME-types
server {
content-types {
css text/css
csv text/csv
html text/html
txt text/plain
blue text/blue
md text/markdown
wiki text/x-mediawiki
haml text/x-haml
yaml text/vnd.yaml
toml text/toml
ini text/plain

js application/javascript
json application/json
pdf application/pdf
xhtml application/xhtml+xml
xml application/xml
plist application/xml

gif image/gif
jpg image/jpeg
png image/png
svg image/svg+xml
webp image/webp
ico image/x-icon

mp3 audio/mpeg
mp4 video/mp4
weba audio/webm
webm video/webm

otf font/otf
ttf font/ttf
woff2 font/woff2
}
}
Example 2: Multiple filename extensions with the same MIME-type
server {
content-types {
jpg image/jpeg
jpeg image/jpeg
JPG image/jpeg
JPEG image/jpeg
}
}

Review

Key points to remember:

  • The content-types section associates filename extensions to MIME-types.
  • The content-type response header will be omitted for any undeclared filename extension.

Mapping filename extensions to MIME types