JSON-LD Format Explained: Read the Braces Without Guessing

JSON-LD is a set of labeled facts written as JSON and connected as linked data. The braces group an object. Quoted words name properties. Colons connect each property to its value. Commas separate one fact from the next.

You do not need to memorize the whole specification to read a schema block. You need to know what the punctuation is doing and how one entity points to another.

Start with one small JSON object

{
  "name": "North Star Bakery",
  "url": "https://example.com/"
}

The opening and closing braces create one object. The object has two properties: name and url. Each property has a text value.

The comma after the first value says another property follows. The last property has no comma after it. An extra comma before the closing brace breaks strict JSON.

Add the linked-data instructions

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "North Star Bakery",
  "url": "https://example.com/"
}

Three keys begin with @ because JSON-LD gives them a special job.

• @context tells a reader how to interpret the vocabulary. For Schema.org markup, the common context is https://schema.org.
• @type says what the object represents. This one is an Organization.
• @id gives the entity a stable identifier that another node can reference.

The @id does not need to be a separate visible page. It is an identifier inside the graph. A fragment attached to a canonical URL is a common choice.

Objects can sit inside other objects

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "A Better Sourdough Schedule",
  "author": {
    "@type": "Person",
    "name": "Maya Chen"
  }
}

The value of author is another object. That nested object says the author is a Person named Maya Chen.

Nesting is readable when the child belongs only to this block. Repeating a full Organization or Person inside many pages can become hard to keep consistent. Stable identifiers let you connect nodes without copying every fact each time.

Square brackets hold a list

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "A Better Sourdough Schedule",
  "image": [
    "https://example.com/images/bread-wide.jpg",
    "https://example.com/images/bread-square.jpg"
  ]
}

The square brackets say image has more than one value. Lists can contain text values, URLs, numbers, or complete objects.

Use @graph for connected entities

A top-level @graph lets one JSON-LD block publish several connected nodes:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "North Star Bakery"
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "name": "North Star Bakery",
      "publisher": {
        "@id": "https://example.com/#organization"
      }
    }
  ]
}

The WebSite does not repeat the whole Organization. Its publisher property points to the Organization identifier. That reference turns two valid objects into a connected graph.

The existing knowledge-graph guide goes deeper into entity relationships and stable IDs.

Text, numbers, true or false, and dates

JSON values have types of their own. Quoted values are text. A number is not quoted. The values true and false are not quoted. Dates are normally quoted text written in a recognized date or date-time format.

{
  "@type": "Offer",
  "price": 49.95,
  "priceCurrency": "USD",
  "availabilityStarts": "2026-11-15T09:00:00-05:00"
}

Schema.org may accept text for some numeric properties, but consistent value types make the data easier to maintain and compare.

Formatting mistakes that stop the block

• Curly quotes: Word processors may replace straight JSON quotes with typographic quotes that do not parse.
• A trailing comma: The final property in an object or list cannot end with a comma.
• An unescaped quote: A quote inside text needs to be escaped or generated safely by the programming language.
• A missing brace or bracket: Every opening character needs its matching close.
• HTML inside raw JSON: Copying an entire script element into a place that expects only the JSON object creates an extra layer the parser cannot read.
• Two objects pasted together: Separate top-level objects need a list or an @graph. They cannot sit beside each other with no container.

Generate JSON instead of assembling punctuation

If a website creates schema from PHP, JavaScript, or another language, build a normal data object and use the language's JSON encoder. Do not join names, quotes, and commas into one long string.

A proper encoder handles quotes, line breaks, Unicode, and escaping. The page still needs content checks, but the format is far less likely to break.

Read the graph in this order

1. Find @context.
2. Find each @type.
3. Find each stable @id.
4. Read the properties attached to each type.
5. Follow properties that point to another @id.
6. Compare every claim with the visible page.

That is enough to understand most website JSON-LD. When the format makes sense, the next move is adding schema markup to a real website.