Add Custom JSON-LD Schema to a Post

SEOvault AI allows you to add custom JSON-LD schema to individual posts and pages. This gives you full control over the structured data output for specific content, useful for advanced use cases or when you need schema types not covered by the guided form.

Where to add custom JSON-LD

Open any post or page in the WordPress editor. Scroll down to the SEOvault AI meta box and expand the Custom Schema JSON section. You’ll see a textarea where you can paste your JSON-LD markup.

How custom JSON-LD works

When you add custom JSON-LD:

Override mode – the custom JSON replaces all auto-generated schema for that post (unless V2 foundational mode is enabled, which merges custom with foundational)
Validation – the JSON is validated for syntax and structure when you save or check schema
Size limits – the input is bounded to prevent performance issues
Withholding – invalid JSON is withheld from output and does not suppress foundational schema (after migration)

If the custom JSON field is empty, SEOvault uses auto-generated schema based on your global settings and post-level guided instances.

Step-by-step: add custom JSON-LD

Open the post or page in the editor.
Scroll to the SEOvault AI meta box.
Expand the Custom Schema JSON section.
Paste your JSON-LD markup in the textarea.
Click Update or Save to save the post.
The Schema Health panel validates the custom JSON automatically.
If there are syntax errors, fix them and save again.

JSON-LD format requirements

Your custom JSON must follow these guidelines:

Valid JSON – the input must be parseable JSON (use a JSON validator if unsure)
Schema.org context – include "@context": "https://schema.org" or use the default
@type property – each node must have a "@type" property with a valid schema.org type
@id property – each node should have a unique "@id" to prevent conflicts
@graph or single node – you can provide a single node object or a graph with "@graph" array

Example: single node

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Your Post Title",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "datePublished": "2024-01-01",
  "image": "https://example.com/image.jpg"
}

Example: graph with multiple nodes

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Your Site Name",
      "url": "https://example.com"
    },
    {
      "@type": "Article",
      "@id": "https://example.com/post/#article",
      "headline": "Your Post Title",
      "author": {
        "@id": "https://example.com/#organization"
      }
    }
  ]
}

Validation and error handling

The Schema Health panel reports issues with custom JSON:

JSON syntax invalid – the JSON cannot be parsed (check for missing commas, quotes, or brackets)
Input too large – the JSON exceeds size limits (reduce the size)
Invalid structure – the JSON does not match expected schema.org patterns

Error states

Invalid – syntax errors prevent the JSON from being used. The panel shows the specific error.
Withheld – after migration, invalid JSON is marked as withheld and does not suppress foundational schema.
Emitted – valid JSON is successfully output on the frontend.

Size limits

Custom JSON input is bounded to prevent performance issues:

Maximum size – approximately 2 MB of raw JSON
Node count – practical limits apply for rendering performance

If your JSON is too large, consider:

Removing unnecessary properties
Splitting into multiple schema instances using the guided form
Using schema templates instead

Using variables in custom JSON

Custom JSON does not support SEOvault’s variable replacement (like %post.title%). If you need dynamic values, use the guided schema form instead. Custom JSON is static and must contain the final values.

Migration behavior

After the V2 migration, custom JSON behavior changes:

Invalid JSON withheld – invalid custom JSON no longer suppresses foundational schema. It is marked as “withheld” and the generated schema is still output.
Editor preview – when the custom field is empty in the editor, the panel previews the generated graph. When invalid JSON is present, the panel shows the generated graph and reports the custom JSON as withheld.
Mode tracking – the plugin tracks whether custom JSON is in “replace” mode (valid) or “invalid_withheld” mode.

Removing custom JSON

To remove custom JSON and return to auto-generated schema:

Open the post in the editor.
Expand the Custom Schema JSON section.
Clear the textarea (delete all content).
Save or update the post.
The Schema Health panel shows the generated schema preview.

Notes and edge cases

Manual only – custom JSON is only output when you explicitly add it. There is no auto-generation for this field.
No validation guarantee – passing syntax validation does not guarantee the schema is correct for Google rich results. Use Google’s Rich Results Test for final verification.
Conflict detection – if multiple sources define the same @id, conflicts are reported in the Schema Health panel.
FAQ and How-to blocks – custom JSON is separate from block-derived schema. FAQ and How-to blocks continue to output their own schema even with custom JSON present.
WooCommerce – if you use custom JSON on product pages, it may conflict with WooCommerce’s built-in schema. Review the live output to verify.