Start Here · Lesson 2 of 15

Reading and Writing JSON-LD

JSON-LD looks intimidating for about five minutes. Then you notice it's just labels and values in curly braces. We'll build one real example, one piece at a time.

9 min readBeginnerOrganization, PostalAddress, Person, WebSite

Meet Fern & Ink

Throughout this course we'll mark up a made-up business: Fern & Ink, a small design and letterpress studio in Minneapolis. Its site lives at https://fernandink.example/. (The .example ending is reserved for examples, so nobody owns it.)

By the end of this lesson you'll have written a block that says who Fern & Ink is, where it is, who founded it, and what its website is. Every later lesson builds on this.

Step 1: The smallest useful block

On a real page, JSON-LD sits inside a <script type="application/ld+json"> tag. That type tells the browser "this isn't code to run, it's data," so it doesn't change how the page looks or behaves. In this lesson we'll show just the JSON inside the tag. Lesson 3 covers where the tag goes.

JSON-LD · Step 1
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Fern & Ink",
  "url": "https://fernandink.example/"
}

Read it as a list of "key": value pairs inside curly braces:

  • "@context": "https://schema.org" says which dictionary the labels come from. It's the same on every block you'll ever write. Copy it and forget it.
  • "@type": "Organization" says what kind of thing this is. Types are capitalized, like Organization, Person, or Event.
  • "name" and "url" are properties: details about the thing. Properties start lowercase and use camelCase, like streetAddress.

Anything that starts with @ is a JSON-LD keyword. It's about the structure of the data, not the business itself.

Step 2: Add details, including a nested object

Some properties are a simple value, like a phone number. Others are a whole thing with its own type. An address isn't one string; it's a PostalAddress with a street, a city, and so on. So we nest a second object, in its own curly braces, as the value.

JSON-LD · Step 2
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Fern & Ink",
  "url": "https://fernandink.example/",
  "logo": "https://fernandink.example/images/logo.png",
  "telephone": "+1-612-555-0142",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "412 Main St SE",
    "addressLocality": "Minneapolis",
    "addressRegion": "MN",
    "postalCode": "55414",
    "addressCountry": "US"
  }
}

The nested object gets its own @type but no @context. It inherits that from the outer block. addressLocality is schema-speak for city, and addressRegion is the state. Writing the phone number with the country code (+1) removes any doubt about where it rings.

Step 3: Lists, and giving things a name tag

Some properties can have more than one value. sameAs lists the other places this business lives online: social profiles, a directory listing, a Wikipedia page if you're lucky. Multiple values go in square brackets, separated by commas. That's an array.

We'll also add an @id. Think of it as a permanent name tag for this item.

JSON-LD · Step 3
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://fernandink.example/#organization",
  "name": "Fern & Ink",
  "url": "https://fernandink.example/",
  "logo": "https://fernandink.example/images/logo.png",
  "telephone": "+1-612-555-0142",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "412 Main St SE",
    "addressLocality": "Minneapolis",
    "addressRegion": "MN",
    "postalCode": "55414",
    "addressCountry": "US"
  },
  "sameAs": [
    "https://www.instagram.com/fernandink_example/",
    "https://www.linkedin.com/company/fernandink-example/"
  ]
}

Why @id matters

An @id is an identifier shaped like a URL. It doesn't have to be a page that loads. The convention is the page URL plus a # and a short label, like https://fernandink.example/#organization.

Once something has an @id, any other item can point to it with a tiny object: { "@id": "https://fernandink.example/#organization" }. That means "the same Fern & Ink I described over there." You write the full details once, and everything else refers back.

This is how you build one connected picture instead of a pile of disconnected facts. The blog post's author, the website's publisher, and the event's organizer can all point to the same organization. Use the exact same @id string everywhere, on every page. One stray character and it's a different thing.

Step 4: Several items in one block with @graph

Fern & Ink has a founder, Maya Lund, and a website. Those are separate things with their own types. You could write three script tags, but @graph is tidier. It's an array that holds several items under one shared @context.

JSON-LD · Step 4 with @graph
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://fernandink.example/#organization",
      "name": "Fern & Ink",
      "url": "https://fernandink.example/",
      "founder": { "@id": "https://fernandink.example/about/#maya" }
    },
    {
      "@type": "Person",
      "@id": "https://fernandink.example/about/#maya",
      "name": "Maya Lund",
      "jobTitle": "Founder",
      "worksFor": { "@id": "https://fernandink.example/#organization" }
    },
    {
      "@type": "WebSite",
      "@id": "https://fernandink.example/#website",
      "name": "Fern & Ink",
      "url": "https://fernandink.example/",
      "publisher": { "@id": "https://fernandink.example/#organization" }
    }
  ]
}

We trimmed the address and sameAs from the Organization so the example fits on screen. In real life they'd stay. Notice how the three items point at each other by @id: the organization's founder is Maya, Maya works for the organization, and the organization publishes the website. No details are repeated.

The pieces at a glance

PieceLooks likeWhat it means
@context"https://schema.org"Use the Schema.org dictionary. Always the same.
@type"Organization"What kind of thing this is.
Property"telephone": "..."A detail about the thing.
Nested object"address": { ... }A detail that is itself a typed thing.
Array"sameAs": [ ..., ... ]More than one value.
@id"https://.../#organization"A name tag other items can point to.
@graph"@graph": [ {...}, {...} ]Several items in one block.

Common mistakes: JSON is picky

JSON-LD is JSON, and JSON has no tolerance for typos. One missing comma and the whole block is ignored, not just the broken line. Here are the usual suspects.

MistakeWrongRight
Single quotes'name': 'Fern & Ink'"name": "Fern & Ink"
Curly "smart" quotes pasted from a doc“name”: “Fern & Ink”"name": "Fern & Ink"
Missing comma between properties"name": "Fern & Ink" then "url": ... on the next linePut a comma after every property except the last
Trailing comma"url": "https://fernandink.example/", }"url": "https://fernandink.example/" }
Comments// our logoDelete it. JSON has no comments.
Relative URLs"logo": "/images/logo.png""logo": "https://fernandink.example/images/logo.png"

Write it in a code editorWord processors, Google Docs, and chat apps quietly swap straight quotes for curly ones. Write JSON-LD in a code editor (VS Code is free) and it will flag most of these mistakes as you type.

Try it

Copy the Step 4 block into your editor. Then add Fern & Ink's phone number to the Organization and an email of hello@fernandink.example. Watch your commas: the line before each new property needs one, and the last property in an object doesn't. For a bonus, add a url to Maya pointing at https://fernandink.example/about/.

Not sure it's right? Paste it into the Schema Markup Validator. Lesson 15 covers testing in detail.

Check yourself

  • I know what @context and @type are for.
  • I can nest an object (like an address) and give it its own @type.
  • I can write a list of values with square brackets.
  • I can explain how @id lets one item point to another.
  • I know when to reach for @graph.
  • I use double quotes, no trailing commas, no comments, and full URLs.
Go deeper on Double Atari

How machines read your page structure and your JSON-LD together: The Machine View, Part 1: How Machines Read Your Outline and Structured Data.