Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
220 lines (161 sloc) 7.78 KB

METADATA.json File Specification

The METADATA.json file is a JSON-formatted metadata file 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 and is provided so that other font distributors (webfont providers or package makers) can better utilize the github.com/google/fonts 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 passing a directory containing OpenType TTF files to the fontbakery fontbakery-build-metadata.py script.

The file uses UTF-8 encoding, though it may also include backslashed Unicode characters in form of \u00e1. Below is an example METADATA.json file for /ofl/abeezee, followed by a brief description of each key and possible values.

{
  "name": "ABeeZee",
  "designer": "Anja Meiners",
  "license": "OFL",
  "visibility": "Sandbox",
  "category": "Sans Serif",
  "size": 24918,
  "fonts": [
    {
      "name": "ABeeZee",
      "postScriptName": "ABeeZee-Italic",
      "fullName": "ABeeZee Italic",
      "style": "italic",
      "weight": 400,
      "filename": "ABeeZee-Italic.ttf",
      "copyright": "Copyright (c) 2011 by Anja Meiners (www.carrois.com post@carrois.com), with Reserved Font Name 'ABeeZee'"
    },
    {
      "name": "ABeeZee",
      "postScriptName": "ABeeZee-Regular",
      "fullName": "ABeeZee",
      "style": "normal",
      "weight": 400,
      "filename": "ABeeZee-Regular.ttf",
      "copyright": "Copyright (c) 2011 by Anja Meiners (www.carrois.com post@carrois.com), with Reserved Font Name 'ABeeZee'"
    }
  ],
  "subsets": [
    "latin",
    "menu"
  ],
  "dateAdded": "2012-09-30"
}

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 directory. Example:

  • "name": "ABeeZee"

designer

Full name of the type designer(s) or foundry who designed the fonts. 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 project
  • "designer": "Multiple Designers" — This is used 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 directory
  • "designer": "TypeTogether" — Sometimes a formal organization designs a family and no individual there can be attributed as the principle designer
  • "designer": "Huerta Tipográfica" — Non-ascii characters are supported as UTF-8
  • "designer": "Huerta Tipogr\u00e1fica" — Sometimes non-ascii characters are encoded this way

This typically matches a string in the first column of profiles.csv

license

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

  • "license": "Apache2"
  • "license": "OFL"
  • "license": "UFL"

visibility

Determines the current release status of the font on Google Fonts. One of 3 possible values:

  • "visibility": "External" — font available on Google Fonts (both website and API)
  • "visibility": "Sandbox" — font will be available shortly on Google Fonts (being tested)
  • "visibility": "Internal" — the font will be served by the Google Fonts API but is not listed on the Google Fonts website

category

Typographic classification, one of 5 possible values:

  • "category": "Serif"
  • "category": "Sans Serif"
  • "category": "Display"
  • "category": "Handwriting"
  • "category": "Monospace"

fonts

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

{
	"name": "ABeeZee",
	"postScriptName": "ABeeZee-Italic",
	"fullName": "ABeeZee Italic",
	"style": "italic",
	"weight": 400,
	"filename": "ABeeZee-Italic.ttf",
	"copyright": "Copyright (c) 2011 by Anja Meiners, with Reserved Font Name 'ABeeZee'"
},

font/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"

font/postScriptName

Value of the font file's NAME table ID 6. If multiple ID 6s exist, they must match. Example:

  • "postScriptName": "ABeeZee-Italic",

Typically this matches the stem of the filename.

font/fullName

Value of the font file's NAME table ID 4. If multiple ID 4s exist, they must match. Example:

  • "fullName": "ABeeZee Italic",

font/style

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.

font/weight

Value of the CSS font-weight property served by Google Fonts. 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, although for fonts with a CSS font-weight property of 100 or 200 then the usWeightClass value will likely be 250, as values of 249 or less suffer smeared rendering on Windows.

font/filename

The font filename. Example:

  • "filename": "ABeeZee-Italic.ttf"

font/copyright

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.

subsets

List of all character subsets available in Google Fonts API for the given font family. 12 possible values:

  • "latin"
  • "latin-ext"
  • "cyrillic"
  • "cyrillic-ext"
  • "greek"
  • "greek-ext"
  • "vietnamese"
  • "khmer"
  • "devanagari"
  • "telugu"
  • "arabic"
  • "hebrew"

dateAdded

Date in YYYY-MM-DD format that the font was first published by Google Fonts, so can be in the future. It used to order the "Date added" sort in the directory. Example:

  • "dateAdded": "2012-09-30"