Google Fonts Guide

METADATA file

🐸 The METADATA.pb files found in the Google Fonts ‘library repo’ (github.com/google/fonts) are Protocol Buffers metadata files that contains some information about the font files served by Google Fonts, some of which typically corresponds to font file internal metadata.

Table of contents

History

This documentation was initiated by Adam Twardoch as a community contributor in 2015, and updated by Dave Crossland as a member of the Google Fonts team in 2020. It is provided so that other font distributors (webfonts providers or font package maintainers) can better use the library repo repository structure.

This metadata is used specifically by Google Fonts for organization and display on the Google Fonts website. It may be useful for others to be able to make sense of the metadata files.

Generation

The file can be partially generated by the gftools add-font script and gftools packager :

gftools add-font path/to/google/fonts/ofl/fontdirname

The file uses UTF-8 encoding.

Below are 2 example METADATA.pb files, first for a family of static font files, and then for a family with variable font files, followed by a brief description of each key and possible values.

Example Static Fonts Family

name: "Example Sans"
designer: "Firstname Lastname, Person Two, Person Three"
license: "OFL"
category: "SANS_SERIF"
category: "MONOSPACE"
date_added: "2021-09-30"
fonts {
  name: "Example Sans"
  style: "normal"
  weight: 400
  filename: "ExampleSans-Regular.ttf"
  post_script_name: "ExampleSans-Regular"
  full_name: "Example Sans Regular"
  copyright: "Copyright 2021 The Example Sans Project Authors (github.com/username/example-sans)"
}
fonts {
  name: "Example Sans"
  style: "italic"
  weight: 400
  filename: "ExampleSans-Italic.ttf"
  post_script_name: "ExampleSans-Italic"
  full_name: "Example Sans Italic"
  copyright: "Copyright 2021 The Example Sans Project Authors (github.com/username/example-sans)"
}
subsets: "latin"
subsets: "latin-ext"
subsets: "menu"
subsets: "vietnamese"
source {
  repository_url: "https://github.com/username/example-sans"
  commit: "d9098c0a72125d411dbb225a2e5a61dc15265ffc"
}

Example Variable Fonts Family

name: "Example Serif"
designer: "Firstname Lastname, Person Two, Person Three"
license: "OFL"
category: "SERIF"
category: "MONOSPACE"
date_added: "2021-09-30"
fonts {
  name: "Example Serif"
  style: "normal"
  weight: 300
  filename: "ExampleSerif[opsz,wght].ttf"
  post_script_name: "ExampleSerif-Light"
  full_name: "Example Serif Light"
  copyright: "Copyright 2021 The Example Sans Project Authors (github.com/username/example-serif)"
}
fonts {
  name: "Example Serif"
  style: "italic"
  weight: 300
  filename: "ExampleSerif-Italic[opsz,wght].ttf"
  post_script_name: "ExampleSerif-LightItalic"
  full_name: "Example Serif Light Italic"
  copyright: "Copyright 2021 The Example Sans Project Authors (github.com/username/example-serif)"
}
subsets: "latin"
subsets: "latin-ext"
subsets: "menu"
subsets: "vietnamese"
axes {
  tag: "wght"
  min_value: 300.0
  max_value: 700.0
}
axes {
  tag: "opsz"
  min_value: 10
  max_value: 144
}
registry_default_overrides {
  key: "opsz"
  value: 24
}
source {
  repository_url: "https://github.com/username/example-sans"
  commit: "d9098c0a72125d411dbb225a2e5a61dc15265ffc"
}

Description of Keys

Most top-level keys provide unique information which is generally not derived from or matching with data inside the font files themselves. Each top-level field can only occur once in the file. The order of the keys does not strictly matter, but the order in this example is typical and is maintained when possible to avoid noisy diff comparisons.

name

Family name used to call the family’s fonts from the Google Fonts API, and shown in the catalog fonts.google.com.

Example: name: "ABeeZee"

date_added

Date in YYYY-MM-DD format that the font was first published by Google Fonts. It is used to order the front page of the GF catalog, both obviously the “date added” sort mode, and also the default “trending mode.”

If you set the date added into the future, then the family will stay at the top of the ‘trending’ sort until that date passes and it trails off like normal.

Once pushed to production, updating it is generally not allowed, although exceptions can be made in limited cases.

Example: date_added: "2021-09-30"

designer

Full name of the type designers or foundries who designed the fonts. Each value typically matches a string in the designer key of info.pb files in the library repo /catalog/designers tree.

Examples:

license

Declares the license of the fonts in the family. Can contain one of 3 possible values:

category

Typographic classification, one of 5 possible values:

Since 2022, it is possible to assign a family with multiple categories (usually two). The second one assigned in the METADATA.pb would be the main one.

fonts

Dictionaries with information specific to each font file in the family. The values in this section typically match those inside the font files. Example:

fonts {
  name: "ABeeZee"
  style: "normal"
  weight: 400
  filename: "ABeeZee-Regular.ttf"
  post_script_name: "ABeeZee-Regular"
  full_name: "ABeeZee Regular"
  copyright: "Copyright 2011 The ABeeZee Project Authors (github.com/username/abeezee)"
}

fonts — name

Family name used to call the font from the Google Fonts API. This must match the name key used at the top level. This typically matches the font file’s name table ID 16, or if that does not exist, the ID 1. If multiple ID 16s or 1s exist, they must match.

Example: name: "ABeeZee"

fonts — style

Value of the CSS font-style property served by Google Fonts. One of 2 possible values:

The Bit 1 in the macStyle bitmask of the font file’s HEAD table should be zero if normal and one if italic. The value of italicAngle in the font file’s POST table should be 0 if normal and a negative value if italic.

fonts — weight

Value of the CSS font-weight property served by Google Fonts. For families offered as static fonts, this will be one of 9 possible values:

Typically this matches the value of usWeightClass in the font file’s OS/2 table.

For variable fonts, this will be one of the 9 possible values that corresponds to the glyf table outline design.

fonts — filename

The font filename. Example: "filename": "ABeeZee-Italic.ttf"

There is a “canonical” naming scheme for font filenames in the Google Fonts library.

For static fonts the pattern is $family-$style.ttf and the allowed values are as follows; These filenames are case sensitive, unlike the default file system of macOS, so Semibold is not allowed, and simply renaming it in macOS Finder will not be effective; it needs to be renamed to something with one more/less character, then renamed back to a correct name.

For variable fonts, the naming scheme is the family name, then an alphabetically sorted, comma separated, list of axes within square brackets. If the family has Italic styles in a second file, then the -Italic particle is appended to the family name.

fonts — post_script_name

Value of the font file’s name table ID 6. If multiple ID 6s exist, they must match. Example: post_script_name: "ABeeZee-Italic"

Typically this matches the stem of the filename.

fonts — full_name

Value of the font file’s name table ID 4. If multiple ID 4s exist, they must match. Example: full_name: "ABeeZee Italic"

fonts — copyright

Copyright notice. Example: copyright: "Copyright 2011 The ABeeZee Project Authors (github.com/username/example-serif)"

Typically this matches the value of the copyright notice in the first lines of the license file. Typically this matches the font file name table ID 0. If multiple ID 0s exist, they must match.

subsets

List of all character subsets available in Google Fonts API for the given font family. They are described as languages, but they are actually script sets.

These subsets are defined in GF Glyphsets repo —with the exception of the menu subset.

The menu subset is the characters of the font family name (defined above) and is used in font picker UIs to render the font name in itself. They must be sorted in alphabetical order.

29 possible values:

registry_default_overrides

Override the default value from the Axis Registry. This is required when axis min and max values do not match the registry default, or when the default value differs from the registered default for the axis.

Repeated for each axis.

Contains 2 required child values:

Example:

registry_default_overrides {
  key: "opsz"
  value: 18
}

→ Look at Roboto Flex for an example of complex Axis Registry override:

source

Indicates the upstream repo URL and the commit at which the font was taken, this important for versioning, but also to keep a trace back the origin of the font since multiple forks can exist for one project.

If the source is a tagged release, then the source entry should look like this:

source {
repository_url: "https://github.com/username/projectname"
archive_url: "https://github.com/username/projectname/releases/download/v2.200/projectname-2.200.zip"
}
This site is open source. Improve this page.