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.
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.
{
"@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, likeOrganization,Person, orEvent."name"and"url"are properties: details about the thing. Properties start lowercase and use camelCase, likestreetAddress.
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.
{
"@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.
{
"@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.
{
"@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
| Piece | Looks like | What 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.
| Mistake | Wrong | Right |
|---|---|---|
| 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 line | Put a comma after every property except the last |
| Trailing comma | "url": "https://fernandink.example/", } | "url": "https://fernandink.example/" } |
| Comments | // our logo | Delete 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
@contextand@typeare 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
@idlets one item point to another. - I know when to reach for
@graph. - I use double quotes, no trailing commas, no comments, and full URLs.
How machines read your page structure and your JSON-LD together: The Machine View, Part 1: How Machines Read Your Outline and Structured Data.