WOFF File Format 1.0

Abstract

This document specifies WOFF, a container format for sfnt type fonts such as OpenType. This format was designed to provide lightweight, easy-to-implement compression of font data, suitable for use in conjunction with the @font-face CSS declaration. Any TrueType/OpenType/Open Font Format file can be losslessly converted to WOFF for Web use (subject to licensing of the font data); once decoded by a user agent, the WOFF file will display identically to the original desktop font from which it was created. Unless the original font file is constructed with anomalies such as incorrect checksums or unreferenced gaps between tables, the decoded WOFF file will be bit-for-bit identical to the original font.

The WOFF format also allows additional metadata to be attached to the file; this can be used by font designers or vendors to include licensing or other information, beyond that present in the original font. Such metadata does not affect the rendering of the font in any way, but may be displayed to the user on request. In addition to standardized metadata, a block of private data may be attached; this may be used by the designer or vendor for any purpose, but will not be interpreted or used in any way by user agents or other processes except by private agreement. Neither metadata nor private data affect the loading or rendering of the font by user agents.

The WOFF format is not expected to replace other font formats such as TrueType/OpenType/Open Font Format or SVG fonts, but provides an alternative packaging solution for use cases where these formats may be less performant, or where licensing considerations make their use less acceptable.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications can be found in the W3C technical reports index at http://www.w3.org/TR/.

By publishing this document, W3C acknowledges that the Submitting Members have made a formal Submission request to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. A W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.

Table of Contents

1. Introduction
2. Overall File Structure
    2.1 Notational Conventions
3. WOFF Header
4. Table Directory
5. Font Data Tables
6. Extended Metadata Block
7. Private Data Block
8. Summary of Conformance Requirements

Appendix A: Extended Metadata Examples
Appendix B: Best Practices for WOFF File Creators
Appendix C: Best Practices for WOFF File Consumers

Footnotes

Version history

Draft of 2009-10-23

Corrected a minor HTML tagging slip; no change in content.

Draft of 2009-10-03

Corrected editing slip in Font Data Tables section; no change in the actual format specification.

Draft of 2009-09-16

First version posted on http://people.mozilla.org/~jkew/ woff/.

Some earlier drafts, now superseded, were circulated via the www-font mailing list and on http://www.jfkew.plus.com/woff/.

1. Introduction

This document specifies a simple compressed file format for fonts, designed primarily for use on the web. The WOFF format is a container for the table-based sfnt structure used in TrueType[1], OpenType[2] and Open Font Format[3] fonts, which are collectively referred to as sfnt-based fonts. A WOFF file is simply a repackaged version of a sfnt-based font with optional compression of the font data tables. The WOFF file format also allows font metadata and private-use data to be included separately from the font data. WOFF encoding tools convert an existing sfnt-based font into a WOFF formatted file, and user agents restore the original sfnt-based font data for use with a webpage.

In general, the structure and contents of decoded font data exactly match those of the original font file. Tools producing WOFF files may provide other font editing features such as glyph subsetting, validation or font feature additions but these are considered outside the scope of this format. Independent of these features, both tools and user agents must assure that the validity of the underlying font data is preserved.

Notational Conventions

The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in RFC 2119[4].

2. Overall File Structure

The structure of WOFF files is similar to the structure of sfnt-based fonts: a table directory containing lengths and offsets to individual font data tables, followed by the data tables themselves. The sfnt structure is described fully in the TrueType[1], OpenType[2] and Open Font Format[3] specifications.

The main body of the file consists of the same collection of font data tables as the original, uncompressed sfnt-based font, stored in the same order, except that each table MAY be compressed, and the sfnt table directory is replaced by the WOFF table directory.

A complete WOFF file consists of a 44-byte header, immediately followed (in this order) by a variable-size table directory, a variable number of font tables, an optional block of extended metadata, and an optional block of private data. Except for padding with a maximum of three null bytes in places where 4-byte alignment of a table length or data block is specified, there MUST NOT be any extraneous data outside the font tables and data blocks as pointed to by the header and table directory entries.

Data values stored in the WOFF Header and WOFF Table Directory sections are stored in big-endian format, just as values are within sfnt-based fonts. The following basic data types are used in the description:

3. WOFF Header

The header includes an identifying signature and indicates the specific kind of font data included in the file (TrueType or CFF outline data); it also has a font version number, offsets to additional data chunks, and the number of entries in the table directory that immediately follows the header:

The flavor field corresponds to the "sfnt version" field found at the beginning of an sfnt file, indicating the type of font data contained. Although only fonts of type 0x00010000 (the version number 1.0 as a 16.16 fixed-point value, indicating TrueType glyph data) and 0x4F54544F (the tag 'OTTO', indicating CFF glyph data) are widely supported at present, it is not an error in the WOFF file if the flavor field contains a different value, indicating a WOFF-packaged version of a different sfnt flavor. (The value 0x74727565 'true' has been used for some TrueType-flavored fonts on Mac OS, for example.) Whether client software will actually support other types of sfnt-based font data is outside the scope of the WOFF specification, which simply describes how the sfnt is repackaged for Web use.

The WOFF majorVersion and minorVersion fields specify the version number for a given WOFF file, which can be based on the version number of the original font but is not required to be. These fields have no effect on font loading or usage behavior in user agents.

The totalSfntSize field is the sum of the uncompressed font table sizes, each padded to a multiple of 4 bytes, plus the size of the sfnt header and table directory. Thus, this is the size of buffer needed to decode the complete WOFF-packaged font (but not metadata, which is not part of the original sfnt file) into a standard sfnt structure. Note that this value MUST be a multiple of 4, because all font tables including the last are to be padded to a 4-byte boundary. If this value is incorrect, a conforming WOFF processor MUST reject the file as invalid.

If either or both of the metadata or private blocks is not present, the relevant offset and length fields MUST be set to zero. If the offset and length fields pointing to the metadata or private data block are out of range, indicating a byte range beyond the physical size of the file, a conforming WOFF processor MUST reject the file as invalid.

The header includes a reserved field; this MUST be set to zero. If this field is non-zero, a conforming WOFF processor MUST reject the file as invalid.

4. Table Directory

The table directory is an array of WOFF table directory entries, as defined below. The directory follows immediately after the WOFF file header; therefore, there is no explicit offset in the header pointing to this block. Its size is calculated by multiplying the numTables value in the WOFF header times the size of a single WOFF table directory. Each table directory entry specifies the size and location of a single font data table.

The format of tag values are defined by the specifications for sfnt-based fonts. The offset and compLength fields identify the location of the compressed font table. The origLength and origCheckSum fields are the length and checksum of the original, uncompressed font table from the table directory of the original font.

The sfnt-based format specifications require that font tables be aligned on 4-byte boundaries. Font tables whose length is not a multiple of 4 are padded with null bytes up to the next 4-byte boundary. Font data tables in the WOFF file have the same requirement: they MUST begin on 4-byte boundaries and be padded with nulls to the next 4-byte boundary. The compLength and origLength fields in the header store the exact, unpadded length.

If the length of a compressed font table would be the same as or greater than the length of the original font table, the font table MUST be stored uncompressed in the WOFF file and the compLength set equal to the origLength. Tools MAY also opt to leave other tables uncompressed (e.g. all tables less than a certain size), in which case compLength will be equal to origLength for these tables as well. WOFF files containing table directory entries for which compLength is greater than origLength are considered invalid and MUST NOT be loaded by user agents. Files containing compressed font tables that decompress to a size larger than origLength are also considered invalid and MUST NOT be loaded.

The sfnt-based font specifications require that the table directory entries are sorted in ascending order of tag value. To simplify processing, WOFF-producing tools MUST produce a table directory with entries in ascending tag value order. User agents MUST likewise assure that the sfnt table directory is recreated in ascending tag order when restoring the font data to its uncompressed state. The ordering of the font tables themselves is independent of the order of directory entries, as described below.

sfnt-based fonts store a checksum for each table in the table directory, and an overall checksum for the entire font in the head table (see the TrueType, OpenType or Open Font Format specifications for the definition of each calculation). Tools producing WOFF files MUST validate these checksums, and correct the values and/or issue an error message if a discrepancy is found.

A WOFF file contains the same set of font tables as the original font from which it was created. This means that the overall font checksum of a font decompressed from a conformant WOFF file should always match the checksum in the original, valid sfnt-based font file, except in the case where the original file included unreferenced data between or after the actual tables; this would affect the overall checksum of the original font, but would be dropped during creation of the WOFF file.

In cases where checksum recalculation is necessary or changes to the original font data are made, e.g., to subset the glyphs in the font or add special tables, conformant tools MUST either remove any digital signature (i.e., a DSIG table) or regenerate the signature (if the necessary credentials are available), and MUST correct all affected checksum values and table offsets, both for individual tables and the overall font data checksum contained in the head table.

Unless the original font has incorrect checksums that are corrected by the WOFF file generator, or extraneous data between tables (discarded by the WOFF generator), the result of creating a WOFF file and then decoding this to regenerate an sfnt font MUST result in a final font that is bitwise-identical to the original.

5. Font Data Tables

The font data tables in the WOFF file are exactly the same as the tables in the original sfnt-based font file, except that each table MAY have been compressed by the compress2() function of zlib[5] (or an equivalent, compatible algorithm). User agents use a function equivalent to the uncompress function of zlib[6] to decompress each table. The underlying format these functions use is described in the ZLIB specification[7].

User agents or other programs that decode WOFF files MUST be able to handle tables that have been compressed. However, the use of compression for font data tables is OPTIONAL for tools generating WOFF files; storing the tables in uncompressed form is permissible.

The font data tables MUST be stored immediately following the table directory, without gaps except for the padding that may be required (up to three null bytes at the end of each table) to ensure 4-byte alignment.

Font tables in WOFF files SHOULD be stored in the same order as the original sfnt-based font and user agents SHOULD restore the original uncompressed font table in identical order if reconstituting the complete font into an sfnt structure. The table order is implied by offset values in the table directory; sorting table directory entries into ascending offset value order produces a list of entries in an order equivalent to that of the font tables.

If either a WOFF-creation tool or a WOFF-consuming user agent reorders or otherwise modifies the collection of font tables, it MUST recalculate the font checksum in the head table, which will be affected by the changed offsets in the sfnt table directory, and remove any DSIG table that is invalidated by the changes. A new signature MAY be added to the modified font, as described by the OpenType and Open Font Format specifications (if appropriate signing credentials are available to the tool involved).

6. Extended Metadata Block

The WOFF file MAY include a block of extended metadata, allowing the inclusion of more extensive metadata than is present directly in the original sfnt-based font file. The metadata block consists of XML data compressed by zlib; the file header specifies both the size of the actual compressed and the original uncompressed size in order to facilitate memory allocation.

If present, the metadata MUST be compressed; it is never stored in uncompressed form. If no extended metadata is present, the metaOffset, metaLength and metaOrigLength fields in the WOFF header MUST be set to zero.

The metadata block MUST follow immediately after the last font table. As font tables MUST be padded with null bytes to a 4-byte boundary, the beginning of the metadata block will always be 4-byte aligned. The end of the metadata block is not padded to a 4-byte boundary unless it is followed by a private data block (below).

If the extended metadata is invalid (for example, the data cannot be decompressed, or it is not well-formed XML), the WOFF processor MUST proceed as if the metadata block is absent; the font itself remains valid and can still be used (provided its main content of font data tables is valid).

The presence (or absence) and content of the metadata block MUST NOT affect font loading or rendering behavior of user agents; it is intended to be purely informative. User agents MAY provide a means for users to view information about fonts (such as a "Font Information" panel). If such information is provided, then they MUST treat the metadata block as the primary source, and MAY fall back to presenting information from the font's name table entries when relevant extended metadata elements are not present.

The extended metadata MUST be well-formed XML. The use of UTF-8 encoding is recommended.

Several elements store their data in text subelements; this is to support localization. The text elements MAY be given a lang attribute. The possible values for the lang attribute can be found in the IANA Subtag Registry[8]. A user agent displaying metadata is expected to choose a preferred language from among those available, following RFC 4647[9]. The user agent SHOULD choose which of the available text elements to display as follows:

1. If a text element is available in the user's preferred language, as determined via an explicit preference or implied by the current locale, use this language.
2. If the user agent has a concept of a list of "acceptable" languages or defaults, try each of these in turn and use the first one found.
3. If there is a text element with no lang attribute, use this; in the event that more than one exists, use the first of them.
4. If no match is found yet, use the first text element. (Thus, the metadata creator can determine the "localization of last resort" simply by choosing which language to put first in each group of text elements.)

metadata element

The main element. This element is required.

attributes
version	A version number indicating the format version of the metadata element. This is currently 1.0. This attribute is required.

All first-level subelements of the metadata are optional, and may occur in any order as children of the top-level metadata element.

Vendors may include additional types of metadata in new elements within the metadata element, or as additional attributes of the elements specified here. Such additional elements or attributes may be ignored by conforming user agents, or may be used (e.g., displayed to the user on request).

uniqueid element

A unique identifier string for the font. This element is recommended, but not required for the metadata to be valid. This element must be a child of the metadata element. This is an empty element.

attributes
id	The identification string.

The string defined in the uniqueid element is not guaranteed to be truly unique, as there is no central registry or authority to ensure this, but it is intended to allow vendors to reliably identify the exact version of a particular font. The use of "reverse-DNS" prefixes to provide a "namespace" is recommended; this can be augmented by additional identification data of the vendor's own design.

vendor element

Information about the font vendor. This element is recommended, but not required for the metadata to be valid. This element must be a child of the metadata element. This is an empty element.

attributes
name	The name of the font vendor. If the vendor element is present in the metadata, this attribute must be present.
url	The url for the font vendor. This attribute is optional.

credits element

Credit information for the font. This can include any type of credit the vendor desires: designer, hinter, and so on. This element is optional. If present, it must be a child of the metadata element and it must contain at least one credit element. This element has no attributes.

credit element

A single credit record. If present, it must be a child of the credits element. This is an empty element.

attributes
name	The name of the entity being credited. If the credit element is present, this attribute must be present.
url	The url for the entity being credited. This attribute is optional.
role	The role of the entity being credited. This attribute is optional.

description element

An arbitrary text description of the font's design, its history, etc. This element is optional. If present, it must be a child of the metadata element. This element may be localized.

license element

The license for the font. This element is optional. If present, it must be a child of the metadata element. This element may be localized.

attributes
url	The url for the license, more information about the license, etc. This attribute is optional.
id	An identifying string for the license. This attribute is optional.

copyright element

The copyright for the font. This element is optional. If present, it must be a child of the metadata element. This element may be localized. This element has no attributes.

trademark element

The trademark for the font. This element is optional. If present, it must be a child of the metadata element. This element may be localized. This element has no attributes.

licensee element

The licensee of the font. This element is optional. If present, it must be a child of the metadata element. This is an empty element.

attributes
name	The name of the licensee. If the licensee element is present in the metadata, this attribute must be present.

Appendix A includes several examples of the content of the metadata block.

7. Private Data Block

The WOFF file MAY include a block of arbitrary data, allowing font creators to include whatever information they wish. The content of this data MUST NOT affect font usage or load behavior. WOFF processors should make no assumptions about the content of a private block; it may (for example) contain ASCII or Unicode text, or some vendor-defined binary data, and it may be compressed or encrypted, but it has no publicly defined format. Conformant user agents will not assume anything about the structure of this data. Only the font developer or vendor responsible for the private block is expected to understand its contents.

The private data block, if present, MUST be the last block in the WOFF file, following all the font tables and any extended metadata block. The private data block MUST begin on a 4-byte boundary in the WOFF file, with up to three null bytes inserted as padding if needed to ensure this. No padding is required at the end of the private data block; any following data does not form part of the WOFF file structure, and MUST be ignored.

If no private data is present, the privOffset and privLength fields in the WOFF header MUST be set to zero. However, as a conforming WOFF processor does not interpret or even need to access the private data in any way, it will simply ignore these fields. Only a private vendor-specific tool would use them.

8. Summary of Conformance Requirements

(sketch, to be expanded....)

This section summarizes key conformance requirements for WOFF files.

Tools creating WOFF files MUST ensure that the results conform to these requirements,
and user agents processing or using WOFF files MUST reject any input files
that fail to meet them.

WOFF header
signature
length
reserved
offset and length of metadata and private blocks
totalSfntLength

WOFF directory
entries in ascending order
compressed length always <= original length
table checksums must be correct for the original data
all offsets 4-byte aligned

Font tables
decompressing zlib-compressed tables must match original length
tables padded with 0 to 3 bytes, to a 4-byte boundary

Metadata
decompressed data must match original length in WOFF header
must be well-formed XML
user agents MUST NOT reject the entire file in case of metadata errors

Appendix A: Extended Metadata Examples

This "dummy" metadata block illustrates the use of the metadata elements described in section 6, including the use of multiple text elements to provide localized versions of certain elements.

<?xml version="1.0" encoding="UTF-8"?>
<metadata version="1.0">
    <uniqueid id="com.example.fontvendor.demofont.rev12345" />
    <vendor name="Font Vendor" url="http://fontvendor.example.com" />
    <credits>
        <credit
            name="Font Designer"
            url="http://fontdesigner.example.com"
            role="Lead" />
        <credit
            name="Another Font Designer"
            url="http://anotherdesigner.example.org"
            role="Contributor" />
        <credit
            name="Yet Another"
            role="Hinting" />
    </credits>
    <description>
        <text lang="en">
            A member of the Demo font family.
            This font is a humanist sans serif style designed
            for optimal legibility in low-resolution environments.
            It can be obtained from fontvendor.example.com.
        </text>
    </description>
    <license url="http://fontvendor.example.com/license"
             id="fontvendor-web-corporate-v2">
        <text lang="en">A license goes here.</text>
        <text lang="fr">Un permis va ici.</text>
    </license>
    <copyright>
        <text lang="en">Copyright ©2009 Font Vendor"</text>
        <text lang="ko">저작권 ©2009 Font Vendor"</text>
    </copyright>
    <trademark>
        <text lang="en">Demo Font is a trademark of Font Vendor</text>
        <text lang="fr">Demo Font est une marque déposée de Font Vendor</text>
        <text lang="de">Demo Font ist ein eingetragenes Warenzeichen der Font Vendor</text>
        <text lang="ja">Demo FontはFont Vendorの商標である</text>
    </trademark>
    <licensee name="Wonderful Websites, Inc." />
</metadata>

A real-life example of a simple metadata block (reproduced by permission of FSI FontShop International GmbH).

<?xml version="1.0" encoding="UTF-8"?>
<metadata version="1.0">
   <uniqueid id="com.fontfont.PraterScriptWeb.7.504.1002"/>
   <vendor name="FSI FontShop International GmbH" url="http://www.fontfont.com"/>
   <credits>
       <credit name="Steffen Sauerteig" role="design"/>
       <credit name="Henning Wagenbreth" role="design"/>
       <credit name="FSI FontShop International GmbH" url="http://www.fontfont.com" role="production"/>
   </credits>
   <description>
       <text lang="en">A FontFont for the web</text>
   </description>
   <license url="http://www.fontfont.com/eula/license_webfonts_v_1_0.html" id="fontfont-web-v1">
       <text lang="en">
	      FontFont web license v 1.0.
	      For details see http://www.fontfont.com/eula/license_webfonts_v_1_0.html
	    </text>
   </license>
   <copyright>
       <text lang="en">2009 Henning Wagenbreth, Steffen Sauerteig published by FSI FontShop International GmbH</text>
   </copyright>
   <trademark>
       <text lang="en">Prater is a trademark of FSI FontShop International GmbH</text>
   </trademark>
</metadata>

Another example of a metadata block (reproduced by permission of Ascender Corporation). This is dynamically generated, with the uniqueid and licensee elements modified to be unique for each customer.

<?xml version="1.0" encoding="UTF-8"?>
<metadata version="1.0">
<uniqueid id="037d0f6b-b5e3-b841-05afa509061b" />
<vendor name="Ascender Corp" url="http://www.fontslive.com" />
<license url="http://www.fontslive.com/info/web-fonts-eula.aspx"
id="ascender-webfonts-eula-v1">
<text lang="en">This font software is the valuable property of Ascender
Corporation and/or its suppliers and its use by you is covered under the
terms of the Web Font license agreement between you and Ascender
Corporation. You may ONLY use this font software with the licensed web site.
Except as specifically permitted by the license, you may not copy this font
software. If you have any questions, please contact Ascender Corp.</text>
</license>
<licensee name="FontsLive.com" />
</metadata>

Appendix B: Best Practices for WOFF File Creators

This appendix highlights aspects of the WOFF specification that are particularly relevant to those creating or packaging fonts in WOFF format, and provides recommended Best Practices for tools or workflows involved in WOFF file creation.

Ensure round-trip fidelity

Any valid WOFF file can be converted back to sfnt format, by decompressing the individual font tables and reconstructing the sfnt header and table directory. The resulting font should always be structurally valid and functionally equivalent to the original font prior to packaging in WOFF format.

However, it is recommended that the result of such a round-trip conversion to WOFF format and back to sfnt should be not only functionally equivalent to the original, but actually bitwise identical. For this to hold true, the original sfnt file should conform to certain norms that are not strictly required by the OpenType/OFF specification, although they are common practice:

Font table padding

The OpenType/OFF specification is not entirely clear about whether all tables in an sfnt font must be padded with NUL bytes to a multiple of 4 bytes in length, or whether this applies only between tables, and the final table of the file may be left unpadded. Most current tools and fonts seem to expect all tables to be padded to a 4-byte boundary, including the last. The WOFF specification assumes this behavior, and specifies that the totalSfntLength field in the WOFF header provides for such padding. To ensure that a given font can be packaged as a WOFF file and then decoded to its original format and give a byte-for-byte identical result, the input font should therefore be padded to a multiple of 4 bytes in length.

No "hidden" data

The OpenType/OFF specification does not explicitly prohibit the presence of "extra" data or padding in between the font tables; as the table directory includes the offset and length of each actual table, such data would simply be ignored. However, the WOFF format makes no provision to preserve such non-font-table data when packaging a font, and therefore it would not survive a round-trip format conversion.

Ensure checksums are correct

The WOFF specification says that table checksums must be validated (and corrected if necessary) by WOFF creators. In order for complete round-trip fidelity, therefore, the checksums in the original sfnt file must also be correct prior to WOFF packaging.

In addition, WOFF creation tools should preserve the order of the font tables. While this is not required for validity or for correct functioning of the font, it is necessary to allow binary round-trip fidelity; and if this is not ensured, then the sfnt checksum and digital signature (if any) can no longer be validated, as these are affected by table ordering.

Distinguish WOFF packaging from other preprocessing and optimization

The WOFF format provides a standard way to package the collection of tables that make up a font, together with added metadata, for delivery to a web browser or other client. It is not concerned with the actual content of the font tables, or how they are used once decoded by the user agent.

In some cases, sites deploying WOFF files as web fonts may wish to subset the character repertoire, optimize table ordering for efficient text layout or rasterization, or remove (or add) optional font tables depending on the particular features needed for a site. These or similar operations are considered modifications to the original font, yielding a new "original" font that becomes the source for WOFF packaging; such modifications are outside the scope of the WOFF specification itself.

Appendix C: Best Practices for WOFF File Consumers

To be written

Footnotes

[1]

Apple TrueType specification. TrueType is a registered trademark of Apple Inc.

[2]

Microsoft OpenType specification. OpenType is a registered trademark of Microsoft Corporation.

[3]

Open Font Format specification (ISO/IEC 14496-22:2009).

[4]

RFC 2119 (Key words for use in RFCs to Indicate Requirement Levels)

[5]

zlib compress2() function

[6]

zlib uncompress() function

[7]

RFC 1950 (ZLIB Compressed Data Format Specification)

[8]

IANA Language Subtag Registry

[9]

RFC 4647 (Matching of Language Tags)