Session 5.2: JSON-LD

Course → Module 5: Schema.org Structured Data

Session 2 of 10

The Preferred Format

JSON-LD stands for JavaScript Object Notation for Linked Data. It is a way to encode structured data as a JSON object embedded in your HTML via a <script> tag. Google explicitly recommends JSON-LD over Microdata and RDFa because it keeps structured data separate from your visible content, making it easier to implement, maintain, and debug.

A JSON-LD block lives in your HTML like this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company Name",
  "url": "https://yoursite.com"
}
</script>

The browser ignores it (it is not executable JavaScript). Search engine crawlers read it. Users never see it. This clean separation is why JSON-LD dominates: you never risk breaking your visible layout by editing structured data.

JSON-LD is invisible to your users and non-executable by browsers. It exists solely for search engines and AI tools to read. This separation of concerns makes it the safest and most maintainable format for structured data.

JSON-LD Anatomy

Every JSON-LD block has the same basic structure. Understanding the anatomy prevents syntax errors that silently break your schema:

Element	Purpose	Example
`@context`	Declares which vocabulary is being used	`"https://schema.org"`
`@type`	Declares the entity type	`"Organization"`
`@id`	Unique identifier for this entity (optional but powerful)	`"https://yoursite.com/#organization"`
Properties	Key-value pairs describing the entity	`"name": "Your Company"`
Nested objects	Related entities embedded within	`"address": {"@type": "PostalAddress", ...}`
Arrays	Multiple values for one property	`"sameAs": ["url1", "url2"]`

A Complete Minimal Example

Here is a minimal but complete Organization JSON-LD block that covers the essential MVES signals:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://yoursite.com/#organization",
  "name": "PT Arsindo Perkasa",
  "url": "https://yoursite.com",
  "logo": "https://yoursite.com/images/logo.png",
  "description": "Indonesian manufacturer and distributor of industrial pumps.",
  "foundingDate": "2015",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "Jl. Raya Bogor No. 15",
    "addressLocality": "Jakarta Timur",
    "addressRegion": "DKI Jakarta",
    "postalCode": "13510",
    "addressCountry": "ID"
  },
  "telephone": "+62-21-8765-4321",
  "sameAs": [
    "https://www.linkedin.com/company/arsindo",
    "https://www.facebook.com/arsindoperkasa",
    "https://www.instagram.com/arsindoperkasa"
  ]
}
</script>

This block declares: an Organization entity with a unique ID, its name, URL, logo, description, founding date, physical address, phone, and links to social profiles via sameAs. This alone covers several MVES requirements from a structured data perspective.

graph TD JSONLD["JSON-LD Block
on Homepage"] --> CTX["@context
schema.org"] JSONLD --> TYPE["@type
Organization"] JSONLD --> ID["@id
Unique Identifier"] JSONLD --> Props["Properties"] Props --> Name["name"] Props --> URL["url"] Props --> Logo["logo"] Props --> Addr["address
(nested PostalAddress)"] Props --> Phone["telephone"] Props --> SA["sameAs
(array of profile URLs)"]

Placement Rules

JSON-LD can be placed in the <head> or <body> of your HTML. Google processes it regardless of placement. Best practice is to place it in the <head> for cleanliness, but if your CMS or template system makes that difficult, placing it anywhere in the <body> works.

You can have multiple JSON-LD blocks on one page. Your homepage might have both Organization schema and BreadcrumbList schema. Each goes in its own <script> tag. Google processes them independently.

Common JSON-LD Errors

These are the errors that most frequently break JSON-LD silently (no visible error on the page, but Google cannot read the data):

Error	Effect	Prevention
Trailing comma after last property	Entire block fails to parse	JSON does not allow trailing commas. Remove them.
Unescaped quotes in string values	JSON syntax breaks	Use backslash to escape: `\"`
Missing closing brackets	Entire block fails	Use a JSON validator before deploying
Using single quotes instead of double	Invalid JSON	JSON requires double quotes for all strings
Incorrect nesting (address outside Organization)	Properties not associated with entity	Validate with Schema Markup Validator

Validating Your JSON-LD

Before deploying any JSON-LD, validate it in two stages:

JSON syntax: Paste your block into jsonlint.com to catch syntax errors (missing commas, brackets, quote issues).
Schema compliance: Paste the full HTML (or URL) into Google's Rich Results Test to confirm Google can read and interpret your markup correctly.

Only deploy to production after both checks pass clean.

Assignment

Write a minimal Organization JSON-LD block for your homepage. Include: @context, @type, @id, name, url, logo, description, foundingDate, address (as nested PostalAddress), telephone, and sameAs (array of your social profile URLs).
Validate the JSON syntax at jsonlint.com. Fix any errors.
If you have access to your website code, add the block to your homepage and run it through the Rich Results Test.
If you cannot deploy yet, save the validated JSON-LD block. You will refine it in the upcoming sessions and deploy it when the complete schema is ready.

JSON-LD