Provide a native API for generating and managing Schema.org JSON-LD structured data

[aniketanandapatil]

Background
WordPress currently provides APIs for managing content, metadata, navigation, taxonomies, authors, and other semantic information, but there is no general-purpose Core API for generating Schema.org structured data in JSON-LD format.

As a result, site owners and developers often need to implement structured data manually through themes, plugins, or custom functions.php code.

This can lead to:

Duplicate Schema markup when multiple plugins or themes generate structured data.
Inconsistent entity relationships between WebSite, WebPage, Article, Person, BreadcrumbList, and other Schema.org entities.
Repeated custom implementations across WordPress websites.
Increased risk of invalid or incomplete structured data.
Difficulty maintaining structured data when WordPress content or site settings change.
Different implementations of the same WordPress content depending on the theme or plugin being used.
Current Workaround
Currently, developers who want to implement Schema.org JSON-LD without relying on an SEO or Schema plugin often have to create custom Schema markup manually in their theme's functions.php file.

For example, a developer may add a hard-coded implementation similar to:

function my_custom_schema_markup() {

	$schema = array(
		'@context' => 'https://schema.org',
		'@graph'   => array(
			array(
				'@type' => 'WebSite',
				'@id'   => home_url( '/#website' ),
				'url'   => home_url( '/' ),
				'name'  => get_bloginfo( 'name' ),
			),
			array(
				'@type' => 'WebPage',
				'@id'   => get_permalink() . '#webpage',
				'url'   => get_permalink(),
				'name'  => wp_get_document_title(),
			),
		),
	);

	echo '<script type="application/ld+json">';
	echo wp_json_encode( $schema );
	echo '</script>';
}

add_action( 'wp_head', 'my_custom_schema_markup' );

For more complex websites, developers then need to add additional conditional logic to functions.php to determine which Schema type should be generated for each type of WordPress content.

For example:

WebSite only on the homepage.
WebPage on applicable pages.
Article / BlogPosting only on individual blog posts.
Person / Author on individual blog posts and author archive pages.
BreadcrumbList on applicable pages except the homepage.
ImageObject when an appropriate image is available.
SearchAction where applicable.
SiteNavigationElement when navigation data is available.
Additional entity relationships using @id.

This approach requires developers to manually maintain the Schema implementation and page-specific conditions.

It can also result in different implementations across themes and websites, even when the underlying WordPress content structure is similar.

The proposed Core API would provide a standardized and extensible alternative to maintaining these Schema implementations manually in functions.php.

Proposed Enhancement
Consider introducing a native and extensible WordPress API for generating Schema.org JSON-LD structured data.

The API would provide developers with a standardized alternative to manually hard-coding Schema markup in functions.php, themes, or plugins.

The API could provide structured representations for commonly used WordPress entities, including:

WebSite (homepage)
WebPage
Article / BlogPosting (individual blog posts)
Person / Author (individual blog posts and author archive pages)
BreadcrumbList (applicable pages except the homepage)
ImageObject
SearchAction
SiteNavigationElement

The generated structured data could be exposed through the existing wp_head mechanism or another appropriate Core API.

The API should be extensible through WordPress filters and actions so that plugins and themes can add or modify supported Schema properties without duplicating the complete implementation.

Proposed Entity Relationships

The proposed API should support relationships between entities using stable @id values.

For example:

Organization
	|
	+-- publisher --> WebSite
	|
	+-- publisher --> Article
	|
	+-- worksFor <-- Person

WebSite
	|
	+-- hasPart --> WebPage

WebPage
	|
	+-- mainEntity --> Article
	|
	+-- breadcrumb --> BreadcrumbList

This would allow multiple Schema entities to reference the same underlying entity instead of creating duplicate representations of the same organization, website, or person.

Example

A WordPress site could generate JSON-LD similar to:

{
	"@context": "https://schema.org",
	"@graph": [
		{
			"@type": "WebSite",
			"@id": "https://example.com/#website",
			"url": "https://example.com/",
			"name": "Example Website"
		},
		{
			"@type": "WebPage",
			"@id": "https://example.com/page/#webpage",
			"url": "https://example.com/page/",
			"name": "Example Page",
			"isPartOf": {
				"@id": "https://example.com/#website"
			}
		}
	]
}

Possible API

A possible Core API could provide functions similar to:

wp_schema_add_entity()
wp_schema_remove_entity()
wp_schema_get_entity()
wp_schema_get_entities()
wp_schema_get_graph()
wp_schema_print_jsonld()

For example:

wp_schema_add_entity(
	array(
		'@type' => 'WebSite',
		'@id'   => home_url( '/#website' ),
		'url'   => home_url( '/' ),
		'name'  => get_bloginfo( 'name' ),
	)
);

The exact API naming and architecture would be subject to review and discussion with WordPress Core maintainers.

Extensibility
The proposed API should provide appropriate filters and actions so that plugins and themes can extend the generated structured data.

For example:

add_filter(
	'wp_schema_entities',
	function ( $entities ) {

		$entities[] = array(
			'@type' => 'Organization',
			'@id'   => home_url( '/#organization' ),
			'name'  => get_bloginfo( 'name' ),
			'url'   => home_url( '/' ),
		);

		return $entities;
	}
);

This would allow plugins and themes to extend the Core-generated Schema without having to replace the complete JSON-LD implementation.

Content-Specific Generation

The implementation should generate Schema based on the actual WordPress content and context rather than generating every Schema type on every page.

For example:

WebSite should be generated for the homepage/site entity.
WebPage should represent applicable WordPress pages.
Article / BlogPosting should only be generated for individual blog posts where the content qualifies as an article.
Person / Author should be associated with applicable posts and author archive pages.
BreadcrumbList should be generated for applicable pages except the homepage.
ImageObject should be generated when a relevant image is available.
SearchAction should only be generated when an appropriate site-search implementation exists.
SiteNavigationElement should be generated from available WordPress navigation data where appropriate.

The API should avoid generating structured data that does not accurately represent the underlying WordPress content.
Compatibility
The proposed API should not automatically override or conflict with structured data generated by existing SEO or Schema plugins.

Existing plugins should be able to:

Detect Core-generated structured data.
Extend Core-generated entities.
Modify supported properties through documented filters.
Disable specific Core-generated entities where necessary.
Integrate their existing Schema implementation with the Core API.

Backward compatibility should be considered so that existing themes and plugins do not need to immediately migrate to the new API.
Goals

1. Provide a standardized Core API for Schema.org JSON-LD.
2. Reduce duplicate structured-data implementations.
3. Reduce the need for developers to maintain hard-coded Schema JSON-LD implementations in functions.php.
4. Allow plugins and themes to extend the generated schema.
5. Establish consistent entity relationships using @id.
6. Make structured data easier for WordPress developers to implement and maintain.
7. Provide content-aware Schema generation based on WordPress objects and context.
8. Reduce the need for developers to repeatedly implement page-specific Schema logic.
9. Avoid generating Schema markup that does not correspond to the actual page content.

Testing
The implementation should include automated PHPUnit tests covering:

Adding Schema entities.
Removing Schema entities.
Retrieving Schema entities.
Multiple entities using @graph.
Entity relationships using @id.
Extensibility through filters.
JSON-LD output.
Empty graph behavior.
Duplicate entity handling.
Content-specific Schema generation.
Homepage versus non-homepage behavior.
Individual post versus page behavior.
Author and author archive behavior.
Breadcrumb generation.
ImageObject generation when an image is available.
Navigation-related Schema generation where applicable.
Documentation
If implemented, the API should include inline documentation and developer documentation covering:

Available Core functions.
Supported Schema entity types.
How entities are registered.
How entities are referenced using @id.
Available filters and actions.
How themes can extend the generated Schema.
How plugins can integrate with the API.
How developers can disable or modify specific entities.
Examples of common implementations.
Expected Benefits
A native structured-data API could provide a consistent foundation for representing WordPress content as structured data while allowing the WordPress ecosystem to build more advanced SEO and semantic-search functionality on top of Core.

A Core API would also reduce the need for developers to maintain large, hard-coded Schema implementations in functions.php.

Instead of manually creating JSON-LD objects and page-specific conditional logic, developers could use a standardized Core API based on WordPress content, metadata, navigation, authors, and other available data.

This could make Schema implementations more consistent across WordPress installations while still allowing themes and plugins to extend or customize the generated structured data.

The proposal is not intended to guarantee improved search rankings.

The primary goal is to provide a standardized, extensible mechanism for representing structured information generated from WordPress content.
Scope
This proposal is focused on providing a Core API and framework for generating and managing Schema.org JSON-LD structured data.

It is not intended to replace existing SEO plugins or provide a complete SEO management system.

SEO plugins and other third-party integrations should be able to build on top of the proposed Core API.