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 specifically used 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.
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 two examples of 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.
name: "Example Sans"
designer: "Firstname Lastname, Person Two, Person Three"
license: "OFL"
category: "SANS_SERIF"
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: "arabic"
subsets: "latin"
subsets: "latin-ext"
subsets: "menu"
subsets: "vietnamese"
primary_script: "Arab"
source {
repository_url: "https://github.com/username/example-sans"
commit: "d9098c0a72125d411dbb225a2e5a61dc15265ffc"
}
minisite_url: "https://myfontwebsite.com"
stroke: "SANS_SERIF"
name: "Example Serif"
designer: "Foundry, Person One Firstname Lastname, Person Two, Person Three"
license: "OFL"
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/MyAccount/MyProject"
files {
source_file: "OFL.txt"
dest_file: "OFL.txt"
}
files {
source_file: "fonts/variable/FontName.ttf"
dest_file: "FontName.ttf"
}
files {
source_file: "documentation/article/ARTICLE.en_us.html"
dest_file: "article/ARTICLE.en_us.html"
}
files {
source_file: "documentation/about/font-image1.png"
dest_file: "arti/font-image1.png"
}
branch: "main"
}
minisite_url: "https://myfontwebsite.com"
stroke: "SERIF"
classifications: "MONOSPACE"
primary_script: "Gujr"
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: "Playpen Sans"
Date in YYYY-MM-DD
format that the font was added to 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.โ
Once pushed to production, updating this date is generally not allowed, although exceptions can be made in limited cases.
Example: date_added: "2021-09-30"
The full name of the type designers or foundries who designed the fonts. The order in which the names are listed here will determine the order of appareance in the About section in the font specimen page. (See below.)
Each designer listed needs to have an entry in the library repo /catalog/designers tree; and each one needs to match a string in the designer
key of info.pb
files there.
Examples:
designer: "Principal Designer, Contributor, Contributor"
โ In 2016 the catalog UI added a feature to show several named contributors on each font family โAboutโ section of the specimen page, where the value of this key is a comma separated list, and the first item in the list is shown the credit โPrincipal Designโ. See the following examples: Rubik, Castoro, Pacificodesigner: "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 occupies the principal designer position. Then, the individual name of the credited designer is followed.designer: "Huerta Tipogrรกfica"
โ Non-ascii characters are supported as UTF-8Declares the license of the fonts in the family. It can contain one of 3 possible values, although all the new fonts added are expected to be licensed by OFL:
license: "APACHE2"
license: "OFL"
license: "UFL"
Typographic classifications, one of 5 possible values:
category: "SERIF"
category: "SANS_SERIF"
category: "DISPLAY"
category: "HANDWRITING"
category: "MONOSPACE"
In 2023, the category
field was complemented with two new fields called stroke
and classifications
. The category
field will continue to exist with no changes to its semantics. We are keeping this field as is because Google products like Workspace and Ads use it, and we donโt want to affect those products.
This key is deprecated in the API (cf. below Stroke and Classification), but still mandatory to fill up in METADATA.pb
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: "Playpen Sans"
style: "normal"
weight: 400
filename: "PlaypenSans[wght].ttf"
post_script_name: "PlaypenSans-Regular"
full_name: "Playpen Sans Regular"
copyright: "Copyright 2023 The Playpen Sans Project Authors (https://github.com/TypeTogether/Playpen-Sans)"
}
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: "Playpen Sans"
Value of the CSS font-style
property served by Google Fonts. One of 2 possible values:
style: "normal"
style: "italic"
Styles marked as normal
in the family METADATA file refers to any upright styles, and italic
refers to any style-linked italic styles.
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.
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": "PlaypenSans[wght].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.ttf
ExampleSans-ThinItalic.ttf
ExampleSans-ExtraLight.ttf
ExampleSans-ExtraLightItalic.ttf
ExampleSans-Light.ttf
ExampleSans-LightItalic.ttf
ExampleSans-Regular.ttf
ExampleSans-Italic.ttf
ExampleSans-Medium.ttf
ExampleSans-MediumItalic.ttf
ExampleSans-SemiBold.ttf
ExampleSans-SemiBoldItalic.ttf
ExampleSans-Bold.ttf
ExampleSans-BoldItalic.ttf
ExampleSans-ExtraBold.ttf
ExampleSans-ExtraBoldItalic.ttf
ExampleSans-Black.ttf
ExampleSans-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].ttf
ExampleSans-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: "PlaypenSans-Regular"
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: "Playpen Sans Regular"
Copyright notice. Example: copyright: "Copyright 2023 The Playpen Sans Project Authors (https://github.com/TypeTogether/Playpen-Sans)"
Typically this matches the value of the copyright notice in the first lines of the license file. It also 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. They are described as languages, but they are actually script sets.
These subsets are defined in GF Subsets 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. This subset is mandatory for all fonts.
The subsets must be sorted in alphabetical order. The possible values are the same as the available nam
files. For example, if a nam
file is named chorasmian_unique-glyphs.nam
the key in METADATA.pb
would be subsets: "chorasmian"
(the nam
file path without โ_unique-glyphs.namโ)
This key aims to indicate which script the specimen page on Google Fonts should display in priority.
The possible values to enter here must refer to the ID of the specified scriptโs textprotos from the lang directory in google/fonts
repo.
Example:
primary_script: "Arab"
This key aims to restrict the number of languages shown in a specimen page. It is mandatory in all Noto fonts but not recommended in non-Nono fonts. It can be useful though when a font support the glyphs of a specific language only.
Example:
languages: "gu_Gujr" # Gujarati
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:
key
, with a string value for the 4 character axis tag code.value
, asย int
ย orย float
ย values.Example:
registry_default_overrides {
key: "opsz"
value: 18
}
โ Look at Roboto Flex for an example of complex Axis Registry override:
Indicates the upstream repo URL, files location 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"
}
The display_name
key is used when the font name should appear differently on the API. The main use of this key is for families which have abbreviated names as a convention, for example the Noto CJK. This is not necessarily clear for the user, so the display_name
key is used to display an unabbreviated name on the specimen page.
Example:
font_name: "Noto Sans JP"
display_name: "Noto Sans Japanese"
Another example of use of this key is when the font family name should be written with an hyphen. Indeed, the hyphen is only authorized to separate the family name from the style name; having a font family name with an hyphen would cause a bad file path and postscript name.
Example:
font_name: "Noto Sans PhagsPa"
display_name: "Noto Sans Phags-pa"
This key allows to link a mini website to the fontโs specimen page. It will appear on top of the page, under the font name, next to the designerโs name. A minisite_url is expected to be mandatory for all the commisioned fonts.
Example:
minisite_url: "https://myfontwebsite.com"
The classification field is a complementary field that can be any combination of Handwriting, Display, Monospace, or Symbols, or it can not be set. So for example, if a font is Handwriting, Display and Monospace all at the same time, use all three. If it does not fit into any of those classifications, there is no need to use the field.
classifications: "HANDWRITING"
classifications: "DISPLAY"
classifications: "MONOSPACE"
classifications: "SYMBOLS"
The stroke field has a single value that is one of SANS_SERIF
, SERIF
, SLAB_SERIF
. It should always be set if one of those options accurately describes the design since some features in the UI only look at the stroke value for some things. Otherwise, if one of the options doesnโt describe the design, it can not be set. Google Fonts Search UI will present stroke
and classifications
as separate search groups so users can combine them and search, say, for fonts that are Serif and Display.
stroke: "SANS_SERIF"
stroke: "SERIF"
stroke: "SLAB_SERIF"
This key overrides the sample texts provided in the languages texprotos (that you can find in the Lang repository). Therefore, the properties of these keys are the same as the ones in a lang textproto. Use it sparingly only for edge cases that would definitely need to specify a determined sample since this override will make this sample fixed, disabling the possibility of picking different languages on the type-tester section of the Specimen page.
If sample text is given within a sample text group (e.g. poster, specimen, masthead), all fields within that group must be provided.
masthead_full
is a 4 glyphs string (e.g. AaBb) used in a single-script masthead. It is used in specimen masthead component.masthead_partial
is a 2 glyphs string (e.g. Aa) that contributes in building a multi-script masthead. It is used in specimen masthead component.styles
is a phrase that has 40-60 chars. Used in presenting the font in different styles in specimen styles component.tester
is a phrase that has 60-90 chars. It is used in presenting the font in GF catalog specimen type tester component.Poster samples are used in presenting the font in GF catalog specimen poster component. The poster module has 3 different strings shown in 3 different styles. A sm
, md
, and lg
string is needed for each of the three rows in the poster. The poster group is only used in Noto fonts.
poster_sm
is a phrase that has 10-15 chars.poster_md
is a phrase that has 8-12 chars.poster_lg
is a word that has 3-8 chars.Specimen samples are used as type ramp samples. The
specimen_48
is a sentence that has 60-70 chars.specimen_36
is a paragraph that has 100-120 chars.specimen_32
is a paragraph that has 140-180 chars.specimen_21
is a passage that has 300-500 chars.specimen_16
is a passage that has 550-750 chars.Example:
sample_text {
masthead_full: "แแ
แแ"
masthead_partial: "แแ"
styles: "แแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ"
tester: "แแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ"
poster_sm: "แแ
แ แแแแ แ
แ แแแแ"
poster_md: "แแ
แ แแแแ"
poster_lg: "แแแแ"
specimen_48: "แแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ"
specimen_36: "แแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ"
specimen_32: "แแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ"
specimen_21: "แแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ\nแแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ\nแแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ"
specimen_16: "แแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ\nแแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ\nแแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ\nแแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ\nแแ
แ แแแแ แ
แ แแแแ แแแแแแแ
แ แ แแแ แแแ แแแแแแแแแแแแ แ แแแ
แแแ แแแ แแแ แแแแแแ แแแแแ แแแแแแแแแแแ แ
แ แแแแแแแแ แแแ แแแแแแ แแแ แแแแ แแแแแแแแแ แแ
แ แแแแ แแ แ แแแ แ
แ แแแแแแแแแแแ"
}
This key overrides the Glyphs page on the UI. Example: Noto Emoji. Not recommended to use in other fonts than icon/symbols one.
Example:
ordered_sample_glyphs {
name: "Smileys and emotions"
glyphs: "๐ ๐ ๐ ๐ ๐ ๐
๐ ๐คฃ ๐ญ ๐ ๐ ๐ ๐ ๐ ๐ฅฐ ๐ ๐คฉ ๐ฅณ ๐ ๐ ๐ฅฒ ๐ฅน ๐ ๐ ๐ ๐ ๐คช ๐ ๐ โบ๏ธ ๐ ๐ ๐ ๐ ๐ ๐ถ ๐ซก ๐ค ๐คซ ๐ซข ๐คญ ๐ฅฑ ๐ค ๐ซฃ ๐ฑ ๐คจ ๐ง ๐ ๐ ๐ฎโ๐จ ๐ค ๐ ๐ก ๐คฌ ๐ฅบ ๐ ๐ฅ ๐ข โน๏ธ ๐ ๐ซค ๐ ๐ค ๐ฐ ๐จ ๐ง ๐ฆ ๐ฎ ๐ฏ ๐ฒ ๐ณ ๐คฏ ๐ฌ ๐ ๐ ๐ ๐ฃ ๐ฉ ๐ซ ๐ต ๐ตโ๐ซ ๐โโ๏ธ ๐โโ๏ธ ๐ซฅ ๐ด ๐ช ๐คค ๐ ๐ ๐ ๐ ๐ ๐ซ ๐ถโ๐ซ๏ธ ๐ฅด ๐ฅต ๐ฅถ ๐คข ๐คฎ ๐คง ๐ค ๐ค ๐ท ๐ค ๐ค ๐ ๐ค ๐ฅธ ๐คฅ ๐คก ๐ป ๐ฉ ๐ฝ ๐ค ๐ ๐ ๐ฟ ๐น ๐บ ๐ฅ ๐ซ โญ ๐ โจ ๐ฅ ๐ฏ ๐ข ๐จ ๐ฆ ๐ซง ๐ค ๐ณ๏ธ ๐ ๐ ๐ ๐ ๐ ๐บ ๐ธ ๐น ๐ป ๐ผ ๐ฝ ๐ ๐ฟ ๐พ โค๏ธ ๐งก ๐ ๐ ๐ ๐ ๐ค ๐ค ๐ค โฅ๏ธ ๐ ๐ ๐ ๐ ๐ ๐ ๐ ๐ ๐ โฃ๏ธ โค๏ธโ๐ฉน ๐ โค๏ธโ๐ฅ ๐ ๐ซ ๐ฅ ๐ค ๐ฃ๏ธ ๐ฃ ๐ง ๐ซ ๐ซ ๐ฉธ ๐ฆ ๐ฆท ๐ฆด โ ๏ธ ๐ ๐ ๐๏ธ ๐ ๐ซฆ ๐
๐ ๐ ๐ฆป ๐ฆถ ๐ฆต ๐ฆฟ ๐ฆพ ๐ช ๐ ๐ ๐ ๐ซถ ๐ ๐ ๐คฒ ๐ค ๐ค ๐ค โ ๐ ๐ซณ ๐ซด ๐ซฑ ๐ซฒ ๐ค ๐ ๐๏ธ โ ๐ ๐ค ๐ค โ๏ธ ๐ค ๐ซฐ ๐ค ๐ค ๐ค ๐ ๐ โ๏ธ ๐ ๐ ๐ ๐ ๐ซต โ๏ธ ๐คณ ๐ ๐
"
}