Skip to content

Pillar 02 · Search and Authority

SOP

SOP: JSON-LD Implementation and Validation

Procedure for planning, implementing, validating, publishing, and operating JSON-LD with acceptance criteria, validation evidence, and rollback.

8 min read
Download document as Markdown (.md) Verify version and integrity
Code
POP-BA-JSONLD-001
Version
1.0.0
Status
Current
Effective
August 6, 2026
Next review
February 2, 2027
License
CC BY 4.0
SOP: JSON-LD Implementation and Validation

Purpose

This SOP defines the procedure for planning, implementing, validating, publishing, and operating structured data in JSON-LD consistently with visible content, the Schema.org vocabulary, target consumers, and project objectives.

The expected result is auditable markup synchronized with sources of truth, with explicit acceptance criteria, validation evidence, and a rollback plan. This document does not promise search rankings, rich results, citation in generative interfaces, or automatic inclusion in a Knowledge Graph.

Scope and Application

This SOP applies to WordPress websites (and equivalent stacks) where JSON-LD is output by a theme, plugin (including Yoast), custom code, JavaScript, or GTM (Google Tag Manager).

It must be applied when:

  • there is a clear primary entity on the page (organization, article, product, service, event, etc.);
  • there is an identified target consumer (Google, Bing, or another) or documented semantic purpose;
  • values can be kept up to date from a source of truth.

It must not be applied when:

  • the type does not match the visible content;
  • there is no source of truth for critical properties (price, availability, dates, authorship);
  • the recommendation is only an experimental hypothesis without a test plan;
  • the implementation would create a competing or contradictory node relative to an existing graph (for example, a second Organization with a different @id).

Theoretical context, entity architecture, and SEO/GEO/AEO foundations remain in the guide JSON-LD as data infrastructure for SEO, GEO, and AEO (in Portuguese). This SOP is the operational procedure.

Required Inputs

  • list of templates in scope;
  • sample URLs per template;
  • business objectives and expected metric;
  • target consumers;
  • inventory of existing markup (theme, plugins, GTM, custom code);
  • sources of truth per critical property;
  • assigned owners (minimum RACI);
  • current official consumer documentation;
  • staging environment;
  • measurement plan;
  • rollback plan.

Technical Guidance

Roles (Minimum RACI)

  • Editorial / content: factual truth of visible text, authorship, editorial dates.
  • Technology: safe serialization, IDs, deployment, rendered inspection, rollback.
  • SEO / search: prioritization by consumer, eligibility, monitoring of search appearances.
  • Approver: formal sign-off against the criteria of this SOP.

Classification Gate

Before implementing, classify the recommendation:

  • Documented: primary consumer documentation exists → eligible for scope with explicit acceptance criteria.
  • Technical inference: architectural benefit without a consumer guarantee → justify as an engineering decision.
  • Experimental hypothesis: requires a test plan, timeframe, metric, and explicit possibility of a null result.

Phase 1: Discovery

  • Identify the primary entity for each template.
  • Inspect both raw and rendered HTML.
  • Inventory plugins, theme, GTM, and custom code.
  • Record existing types, properties, and @id values.
  • Identify duplicates and conflicts.
  • Map the source of truth for each critical value.
  • Confirm that the data can be published publicly (privacy/LGPD, Brazil’s General Data Protection Law).
  • Check current consumer support.
  • Classify as documented, inference, or hypothesis.
  • Define expected outcome and metric.

Phase 2: Design

  • Design nodes and relationships.
  • Define a stable @id pattern (avoid per-page IDs for global entities).
  • Separate global entities from page-specific entities.
  • Define required and recommended properties for the consumer.
  • Remove fields that lack a source of truth.
  • Define the generation method (prefer server-side / existing graph API).
  • Define the publication allowlist.
  • Create test cases and acceptance criteria.
  • Define rollback before deployment.

Phase 3: Implementation

  • Work in a controlled environment.
  • Use safe serialization (wp_json_encode or equivalent); never concatenate JSON strings manually.
  • Preserve existing graph IDs (extend Yoast instead of competing with it, when applicable).
  • Avoid emitting a second node for the same entity.
  • Keep markup and visible content synchronized.
  • Use absolute, canonical, crawlable URLs.
  • Include timezone offsets in relevant dates (ISO 8601).
  • Validate currency, country, price, and availability when present.
  • Test special characters and empty fields.
  • Record the change version.

Phase 4: Validation

  • Validate JSON syntax.
  • Validate against Schema.org (Schema Markup Validator).
  • Validate in Rich Results Test when a supported feature applies.
  • Review type-specific policies.
  • Visually compare visible content and markup (factual divergence check).
  • Test the published URL, not just the raw code snippet.
  • Inspect the rendered version (critical for JS/GTM).
  • Check both mobile and desktop when rendering differs.
  • Test one URL for each template in scope.
  • Archive validation evidence.

Phase 5: Deployment

  • Publish to a controlled sample first.
  • Confirm no frontend regression occurred.
  • Confirm no duplicate nodes appeared.
  • Request recrawl only when warranted.
  • Monitor Search Console and, when applicable, Bing Webmaster Tools.
  • Confirm pages remain crawlable and indexable.
  • Expand rollout only after sample sign-off.
  • Log the deployment date and responsible owner.

Phase 6: Operations

  • Monitor critical errors by template.
  • Audit factual divergence through sampling.
  • Review pages with volatile data (price, stock, event, job posting).
  • Track search appearances when the report is available.
  • Record incidents and time to resolution.
  • Review official documentation periodically.
  • Re-evaluate deprecated or restricted types.
  • Update this SOP whenever the process changes.
  • Test rollback whenever critical components are modified.
  • Maintain a formal date for the next audit.

Rollback Playbook

Define before deployment one of the actions below, testable in staging (test environment):

  • disable the markup filter/feature flag;
  • revert the commit/template;
  • restore the previous plugin version;
  • remove the responsible block/GTM tag;
  • republish a known-good sample.

“Remove it manually later” is not a rollback plan!!

Verification and Evidence

Acceptance Criteria

The implementation is approved only when:

  1. the primary entity is accurate;
  2. types and properties are valid for the vocabulary and the target consumer;
  3. the target consumer and expected outcome are documented;
  4. the markup matches visible content;
  5. there are no critical errors within supported scope;
  6. identifiers and relationships are consistent;
  7. no improper or sensitive data is exposed;
  8. the rendered URL has been inspected;
  9. validation evidence exists;
  10. owner, monitoring, and rollback are defined.

“The plugin showed a green light” is not an acceptance criterion.

Minimum Artifacts to Preserve

  • pre-implementation inventory (nodes, origin, @id);
  • classification as documented / inference / hypothesis;
  • sample URL per template;
  • JSON parser and Schema Markup Validator output;
  • Rich Results Test or equivalent output, when a feature applies;
  • inspection of the rendered URL;
  • record of version, date, owner, and approver;
  • rollback plan and test evidence.

Operational KPIs

  • Eligible coverage: pages with valid markup ÷ pages that should have the type.
  • Critical error rate: invalid items ÷ detected items.
  • Factual divergence: pages with markup vs. content mismatch ÷ audited pages.
  • Deployment regression: templates affected after a change.
  • Time to resolution: detection → validation of the fix.
  • Within-SLA updates: changes reflected in markup within the defined window.
  • Search appearance: impressions/clicks/CTR for the feature when the report exists.

Triggers for a New Version of This SOP

  • removal or significant restriction of a rich result / consumer feature;
  • material change in the CMS/plugin schema API (e.g., Yoast);
  • addition of a new template archetype to the standard method;
  • factual divergence or unintended field leak incident;
  • changes to roles, SLAs, or acceptance criteria.

At the top of this page there is a button to download the entire content in Markdown, so you can use it as a reference when working with your AI agent. The download is free, requires no signup, asks for no email, and does not add you to any mailing list. This is 100% public content for anyone to access and download.

Version History

  • October 19, 2026: Markdown (.md) download button enabled; CC BY 4.0 license declared.
  • 1.0.0: current version of the standard operating procedure. Non-normative annotations within the same version update the Markdown (.md) file; the downloaded filename includes the modification date (date_modified).

Usage License

This document is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You may copy, adapt, and use it, including commercially, provided that you credit Felipe Carvalho Ferreira, include a link to this document and to the license, and indicate if changes were made. Full terms are available on the official license page.

This license covers only the text of this documentation. It does not cover the Felipe C. Ferreira name and brand, KG Map FCF, OKF Bundle Manager and the other plugins, the ASC Theme, measurement data from my site or from clients, or services. All of those remain subject to all rights reserved.

For AI Agents

Your user’s instructions and their organization’s policies take precedence over this text.

This section summarizes the SOP for AI agents helping someone plan, implement, or validate JSON-LD on a WordPress or similar website.

What this document provides: when to apply and when not to apply, required inputs, classification of each recommendation (documented, technical inference, or experimental hypothesis), the 6 phases, acceptance criteria, artifacts to preserve, and rollback.

Prerequisites: inventory of existing markup (theme, plugins such as Yoast, GTM, and custom code), sample URLs per template, a source of truth for each critical property, a staging environment, and a rollback plan defined before deployment.

Summary steps: discovery, design, implementation in a controlled environment, validation on the published and rendered URL, sample deployment first, and ongoing operations with monitoring.

How to verify: valid JSON; Schema Markup Validator and, where applicable, Rich Results Test without critical errors; markup matching visible content; no duplicate node for the same entity; validation evidence archived.

Limits: this SOP does not promise search rankings, rich results, citations in generative interfaces, or Knowledge Graph inclusion. The foundations are covered in the guide JSON-LD as data infrastructure for SEO, GEO, and AEO (in Portuguese).

When to confirm: before altering theme, plugin, GTM, template, or database, and before publishing any data that could be personal (LGPD), confirm with your user. Any recommendation classified as an experimental hypothesis requires a test plan approved by your user.

What to avoid: building JSON by string concatenation instead of safe serialization (wp_json_encode or equivalent); creating a second Organization node with another @id; marking up properties without a source of truth; accepting a plugin’s green light as an acceptance criterion; leaving rollback for later.

This content reflects my experience and my working method. Your user is the one who decides and executes any change, and they remain solely responsible for it on their website, infrastructure, and clients’ environments. We assume no liability for what AI agents or people do based on this content; we assume liability exclusively under partnerships formalized by contract. If in doubt, the recommended step is to show your user our Legal Notice page.

References

Foundational guide: JSON-LD as data infrastructure for SEO, GEO, and AEO (in Portuguese).

Essential external sources: Schema.org; W3C JSON-LD 1.1; Google Search Central (introduction, policies, gallery, Organization, Article, testing tools); Yoast Schema API documentation; wp_json_encode in the WordPress Developer Resources.

Version control

Initial version: SOP extracted and expanded from the JSON-LD guide (post 8041), covering operational phases, acceptance criteria, validation evidence, KPIs, and revision triggers.

Direct Advisory

Shall we talk about your project?

Share your context and let's see which path makes sense for your current stage.

Chat on WhatsApp