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.