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.
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 (webfont providers or font package maintainers) can better utilize the library repo repository structure. This metadata is used by Google Fonts specifically, but since the Google Fonts repo also happens to be a handy, consistently organized collection of libre fonts, it may be useful for others to be able to make sense of the metadata files.
The file can be partially generated by the gftools add-font tool
gftools add-font ../ofl/newfamily
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.
FontBakery should be validating METADATA files, such as checking that:
- all fonts in a family folder are enumerated in METADATA
- those files support at least what is declared in METADATA
- all axes declared have ranges that fit within what the GF Axis Registry supports
Files can include additional axes (or axis range) beyond what is declared in METADATA.pb (or the GFAR).
For example, Signika has a NEGA axis, and as of 2020-07 this is intentionally not in the GFAR at this time, so it should be valid for Signika to declare only wght;
similarly, if Signika had wdth but we didn't want to ship it in the API yet, then declaring only wght should be fine.
name: "Example Sans"
designer: "Firstname Lastname, Person Two, Person Three"
license: "OFL"
category: "SANS_SERIF"
date_added: "2012-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 2012 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 2012 The \'Example Sans\' Project Authors (github.com/username/example-sans)"
}
subsets: "latin"
subsets: "latin-ext"
subsets: "menu"
subsets: "vietnamese"
name: "Example Serif"
designer: "Firstname Lastname, Person Two, Person Three"
license: "OFL"
category: "SERIF"
date_added: "2012-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 2020 The \'Example Serif\' 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 2020 The \'Example Serif\' 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
}
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.
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 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: "2012-09-30"
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:
designer: "Anja Meiners"— An individual's name is preferred; typically there is an individual who is the principle designer of the typeface family, even if they are no longer the primary maintainer of the projectdesigner: "TypeTogether"— Sometimes a formal organization designs a family and no individual there can be attributed as the principle designerdesigner: "Huerta Tipográfica"— Non-ascii characters are supported as UTF-8designer: "Multiple Designers"— This was used 2011 to 2016, when several people are involved in the design of a project, but are not working in a formal organization, or listing all their names would be too long to work well in the catalog UI as it was from 2011 to 2016. Many of these values persist, but should be updated as followsdesigner: "Principal Designer, Contributor, Contributor"— In 2016 the catalog UI added a feature to show several named contributors on each font family specimen page, where the value of this key is a comma separated list, and the first item in the list is shown the the credit "Principal Design" (Examples: Rubik, Pacifico)
Declares the license of the fonts in the family. Can contain one of 3 possible values:
license: "APACHE2"license: "OFL"license: "UFL"
Typographic classification, one of 5 possible values:
category: "SERIF"category: "SANS_SERIF"category: "DISPLAY"category: "HANDWRITING"category: "MONOSPACE"
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 (c) 2011 by Anja Meiners, with Reserved Font Name \'ABeeZee\'"
}
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"
Value of the CSS font-style property served by Google Fonts.
One of 2 possible values:
style: "normal"style: "italic"
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.
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:
"weight": 100"weight": 200"weight": 300"weight": 400"weight": 500"weight": 600"weight": 700"weight": 800"weight": 900
Typically this matches the value of usWeightClass in the font file's OS/2 table.
Some fonts with a CSS font-weight property of 100 or 200 then the usWeightClass value may be 250, as values of 249 or less in CFF fonts suffered from blurry rendering on older versions of Windows, but in 2020 this is no longer necessary.
For variable fonts, this will be one of the 9 possible values that corresponds to the glyf table outline design.
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.
ExampleSans-Thin.ttfExampleSans-ThinItalic.ttfExampleSans-ExtraLight.ttfExampleSans-ExtraLightItalic.ttfExampleSans-Light.ttfExampleSans-LightItalic.ttfExampleSans-Regular.ttfExampleSans-Italic.ttfExampleSans-Medium.ttfExampleSans-MediumItalic.ttfExampleSans-SemiBold.ttfExampleSans-SemiBoldItalic.ttfExampleSans-Bold.ttfExampleSans-BoldItalic.ttfExampleSans-ExtraBold.ttfExampleSans-ExtraBoldItalic.ttfExampleSans-Black.ttfExampleSans-BlackItalic.ttf
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.
ExampleSans[wdth,wght].ttfExampleSans-Italic[wdth,wght].ttf
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.
Value of the font file's name table ID 4.
If multiple ID 4s exist, they must match.
Example:
full_name: "ABeeZee Italic"
Copyright notice. Example:
copyright: "Copyright (c) 2011 by Anja Meiners, with Reserved Font Name \'ABeeZee\'"
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.
List of all character subsets available in Google Fonts API for the given font family.
These subsets are defined in github.com/googlefonts/gftools/blob/main/Lib/gftools/encodings 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.
29 possible values:
arabicbengalichinese-simplifiedcyrilliccyrillic-extdevanagariethiopicgreekgreek-extgujaratigurmukhihebrewjapanesekannadakhmerkoreanlaolatinlatin-extmalayalammenumyanmaroriyasinhalatamilteluguthaitibetanvietnamese