Glossary of Terms for theme.json | CSS-Tricks

WordPress Block Theme CSS and Style Settings Guide

Common JSON terms

We’re going to spend a quick moment getting familiar with JSON-related terms before jumping to the next section that outlines the six different types of JSON data types.

JSON

JSON refers to JavaScript Object Notation, a machine-readable data-sharing format. As the name suggests, JSON is derived from JavaScript and applied to many other languages like PHP, Ruby, Python, etc. Many software applications, including React, Gatsby, VS Code, and others, use JSON for settings environments.

Object

Objects are key-value pairs separated by colons : and contained inside curly brackets ({}). You can think of it like CSS in a way. We have a property (or key) followed by a value that defines the property:

color: #9DFF20;

In JSON, that is represented as an object like this:

{ "color": "#9DFF20" }

Note: A JSON object property is also called a field or key. A key-value pair is also called an item or data.

And like a CSS ruleset can contain many key-value pairs, so can a JSON object. This example is an object with three keys — color, name, and slug — each with a corresponding value:

{ "color": "#9DFF20", "name": "Primary", "slug": "primary" }

Contrary to CSS, JSON is not a “forgiving” language, and even one typing error can break the entire website.

Nested object

Objects in JSON can contain other objects. We call these nested objects, and it’s what makes JSON a structured language.

{
  "object1": {
    "object1a": "value",
    "object1b": "value"
  },
  "object2" : {
    "object2a": "value",
    "object2b": "value"
  }
}

Let’s take an example straight from the emptytheme theme.json file:

Array

An array is a comma-separated group of objects in square brackets ([]). The idea is that we might need to define more than one object at a time. A good example is defining the colors of a block theme’s color palette. An array allows us to define a group of colors for that palette:

JSON data types

JSON values must be one of the six data types: a string, a number, an object, an array, a boolean (true or false), and null. JSON data are assessed using dot . notation.

Here is an abbreviated modified TT3 theme.json object file showing all the data types:

{
  "version": 2, // 1: Number (no quotes)
  "settings": {
    "appearanceTools": true, // 2: Boolean (true or false, no quotes)
    "useRootPaddingAwareAlignments": false,
    "color": {
      "palette": [ // 3: Array of string object palette
        { 
          "color": "#ffffff", // 4: Object (in curly brackets)
          "name": "Base",
          "slug": "base"
        }
      ]
    },
    "layout": { "contentSize": "650px"}, // 5: String (in double quotes)
    "styles": {
      "typography": { "lineHeight": "1.6" },
      "spacing": { "blockGap": null } // 6: null (no quotes)
    }
  }
}

Additional resources

HTML and CSS (Block Editor Handbook | Explanations)
Introducing JSON (JSON.org)
An Introduction to JSON (DigitalOcean)
What is JSON (REST API Tutorial)

Next up…

Now that we have a solid understanding of JSON and how it is structured in the theme.json of WordPress block themes, let’s take a closer look at how global styling works. We can define default styles for a block theme directly in theme.json. We can also use the Global Styles UI in WordPress.

How do those work together? What sort of settings are available? When should you use one over the other? We’ll answer those questions and more next.