JSON Structured Data: Connect Page Entities with JSON-LD

Decide what the JSON describes

JSON structured data for a web page usually means JSON-LD: JSON objects that use a context to give properties a defined meaning. Ordinary JSON might be a private application response, a settings file or a database export. Its ability to parse does not automatically make it structured data that a search engine understands.

Start with the actual page and its entities. An article has a headline, an author and a publication history. A person has a name and an identity that can be reused across several articles. A navigation trail describes where a page sits within a site. These objects have different purposes even when they appear in one document.

Use identifiers to connect a small graph

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "BlogPosting",
      "@id": "https://example.com/guides/maps/#article",
      "headline": "Reading a neighborhood map",
      "author": {"@id": "https://example.com/about#editor"}
    },
    {
      "@type": "Person",
      "@id": "https://example.com/about#editor",
      "name": "Example Editor",
      "url": "https://example.com/about#editor"
    }
  ]
}

This is an illustrative graph, not a complete publishing template. Replace the example domain, author and headline with verified facts. The article refers to the person by the same identifier used by the Person object. The article and the person do not share one identifier, because they are different things.

The JSON-LD specification explains the context, node identifiers and graph model. A context is not a JSON Schema validation file. It supplies vocabulary mappings; it does not, by itself, require an article to have every property your publishing system expects.

Keep one source record for repeated facts

Store the editorial headline once and derive the visible heading and structured headline from that record. Do the same for the author link. If a page title is deliberately shortened for a browser tab, keep that presentation choice separate from the full editorial headline rather than accidentally overwriting the article's identity.

Use persistent identifiers through ordinary wording changes. Renaming an article does not necessarily create a new article entity. Conversely, assigning the same article identifier to every page joins unrelated records together. Choose a consistent URL policy and inspect the generated output from more than one page.

Serialize before embedding in HTML

Build a JavaScript object and serialize it instead of assembling JSON with string concatenation. Quotation marks, backslashes and line breaks inside titles must remain string content. When embedding serialized JSON in an HTML script element, handle the HTML parser's closing-script sequence as well as JSON syntax.

function serializeForHtml(data) {
  return JSON.stringify(data).replace(/</g, "\\u003c");
}
const data = {headline: "A </script> example"};
const serialized = serializeForHtml(data);
console.assert(!serialized.includes("<"));
console.assert(JSON.parse(serialized).headline === data.headline);

The replacement keeps the represented string intact after JSON parsing. It avoids putting a literal opening angle bracket into the embedded JSON text. Apply this to the serialized JSON, not to the source object, and do not run another generic HTML-escaping step that changes JSON quotation marks into entity text inside a script.

Separate the checks you can actually perform

First parse the JSON. Next inspect vocabulary and references, including whether the author's identifier is spelled consistently. Then compare the data with the visible page. Finally, use the relevant search platform's feature-specific test when a currently supported search appearance is the goal.

The local Structured Data Validator provides a syntax and basic structure check. It does not expand every remote context, verify the truth of a biography or certify eligibility for a search feature. Treat a successful local result as one stage of review.

Before publishing, test an ordinary headline and another containing quotes, an ampersand and a closing-script example. Open the resulting HTML, parse its actual JSON-LD blocks and confirm that the page has no unexpected extra elements. This catches integration defects that a standalone JSON text box cannot see.

Also test a missing optional field. JavaScript serialization omits an object property whose value is undefined, while an explicit null remains in the JSON. Decide whether the publishing record should omit an unknown value or reject the incomplete article. Do not substitute an empty author object merely to avoid a validation message: the output should reflect what is known about that specific page.

Related guides

Paginate JSON Data in JavaScript: Slice a Stable Array

Build client-side pagination with explicit page bounds, empty-state handling and stable ordering, and know when server pagination is required.

Fetch JSON in JavaScript: Check Status and Validate the Response

Read a JSON response with Fetch, distinguish HTTP and parsing failures, and validate the fields your interface uses before rendering a result.

WordPress JSON-LD: Inspect and Maintain the Rendered Markup

Find the JSON-LD WordPress already emits, choose one publishing owner, serialize content safely, and verify changes on rendered article pages.