Download the PHP package evabee/schema-org-json-ld without Composer

schema-org-json-ld

PHP and TypeScript/JavaScript library for generating schema.org JSON-LD structured data for Google Rich Results. Covers all 31 Google Search Gallery categories backed by 89 schema classes/modules (88 primary schema types + 1 additional sub-type), with type-safe constructor-promoted properties and automatic serialization.

Validated against the Google Rich Results Test via the schema-org-json-ld-qc validation suite.

Table of Contents

• Installation
• Quick Start
• Supported Types
• Usage Examples
  • Article
  • Breadcrumb
  • Carousel
  • Course
  • Dataset
  • Discussion Forum
  • Education Q&A
  • Employer Aggregate Rating
  • Event
  • FAQ
  • Image Metadata
  • Job Posting
  • Local Business
  • Math Solver
  • Movie
  • Organization
  • Product
  • Profile Page
  • Q&A
  • Recipe
  • Review Snippet
  • Software App
  • Speakable
  • Subscription / Paywalled Content
  • Vacation Rental
  • Video
• API Reference
• Testing
• Known Validator Limitations
• Contributing
• License

Installation

TypeScript / JavaScript

PHP

Note: The vendor name evabee is intentional. Due to Packagist requiring excessive GitHub permissions, the default evalok vendor namespace is unavailable. The package is otherwise identical.

Quick Start

PHP

The pattern is always the same: instantiate a schema class, pass it to JsonLdGenerator::SchemaToJson(), and embed the result in a <script type="application/ld+json"> tag.

TypeScript / JavaScript

Supported Types

Usage Examples

Article

Supports Article, NewsArticle, and BlogPosting. NewsArticle and BlogPosting extend Article and share the same constructor — only @type differs.

TypeScript:

Output is identical to the PHP JSON example above.

Use NewsArticle or BlogPosting by substituting the class name — the constructor is identical:

Breadcrumb

TypeScript:

Output is identical to the PHP JSON example above.

Carousel

Use ItemList with ListItem entries pointing to the URLs of items in the carousel (articles, recipes, movies, etc.).

TypeScript:

Output is identical to the PHP JSON example above.

Course

TypeScript:

Output is identical to the PHP JSON example above.

Dataset

TypeScript:

Output is identical to the PHP JSON example above.

Discussion Forum

TypeScript:

Output is identical to the PHP JSON example above.

Education Q&A

TypeScript:

Output is identical to the PHP JSON example above.

Employer Aggregate Rating

TypeScript:

Output is identical to the PHP JSON example above.

Event

TypeScript:

Output is identical to the PHP JSON example above.

FAQ

TypeScript:

Output is identical to the PHP JSON example above.

Image Metadata

TypeScript:

Output is identical to the PHP JSON example above.

Job Posting

TypeScript:

Output is identical to the PHP JSON example above.

Local Business

TypeScript:

Output is identical to the PHP JSON example above.

Math Solver

TypeScript:

Output is identical to the PHP JSON example above.

Movie

TypeScript:

Output is identical to the PHP JSON example above.

Organization

TypeScript:

Output is identical to the PHP JSON example above.

hasMerchantReturnPolicy, hasMemberProgram, and hasShippingService accept MerchantReturnPolicy, MemberProgram, and ShippingService objects respectively (or arrays of those objects).

Additional organization identifier fields supported by Organization:

• taxID
• vatID
• naics
• duns
• leiCode
• iso6523Code
• globalLocationNumber

Product

TypeScript:

Output is identical to the PHP JSON example above.

Profile Page

TypeScript:

Output is identical to the PHP JSON example above.

Q&A

TypeScript:

Output is identical to the PHP JSON example above.

Recipe

TypeScript:

Output is identical to the PHP JSON example above.

Review Snippet

TypeScript:

Output is identical to the PHP JSON example above.

Review and AggregateRating are typically embedded inside a Product, Movie, Recipe, etc. rather than used standalone. The review and aggregateRating properties are available on all relevant schema types.

Software App

Supports SoftwareApplication, MobileApplication, and WebApplication. The subtype classes share the same constructor as SoftwareApplication.

TypeScript:

Output is identical to the PHP JSON example above.

Use MobileApplication or WebApplication by substituting the class name:

Speakable

The SpeakableSpecification is used via the speakable property on Article (and its subtypes).

TypeScript:

Output is identical to the PHP JSON example above.

Subscription / Paywalled Content

Mark paywalled content using WebPageElement via the hasPart property on Article.

TypeScript:

Output is identical to the PHP JSON example above.

Vacation Rental

TypeScript:

Output is identical to the PHP JSON example above.

Video

TypeScript:

Output is identical to the PHP JSON example above.

Multiple Schemas per Page (@graph)

When a page contains multiple rich result entities (for example an Article and a BreadcrumbList), you can combine them into a single JSON-LD block using @graph.

API Reference

PHP: JsonLdGenerator::SchemaToJson(TypedSchema $schema): string

Serializes any schema object to a JSON-LD string ready to embed in HTML.

Behaviour:

• Automatically adds @context (https://schema.org/) and @type (from the class constant).
• A_SCHEMA_TYPE can be either a string ('Product') or an array of strings (['MathSolver', 'LearningResource']).
• Skips null properties — only set properties are included in the output.
• Recursively serializes nested TypedSchema instances.
• Backed string enums (e.g. ItemAvailability, OfferItemCondition, EventStatusType) are automatically serialized to their .value (the full schema.org URL).
• Arrays of schema objects and primitives are both handled correctly.

TypeScript: JsonLdGenerator.schemaToJson(schema: TypedSchema): string

TypeScript uses the same serialization behavior with a lowercase schemaToJson method name:

TypeScript: JsonLdGenerator.schemasToJson(...schemas: TypedSchema[]): string

Use this variant to generate an @graph payload from multiple schema objects:

TypedSchema (abstract base class)

All schema classes extend TypedSchema.

• PHP uses public const A_SCHEMA_TYPE = 'TypeName';
• TypeScript uses static readonly schemaType = 'TypeName';

The only requirement is that each class defines the schema type constant/property:

For schema.org properties that use names that are not valid language identifiers (for example mathExpression-input), define a property map:

Schema classes use constructor promotion — all data is passed via the constructor and stored as public properties. No methods are needed beyond the constructor.

Testing

See the php/test/unit and ts/test directories for the full test suites.

Known Validator Limitations

When validating JSON-LD output with third-party validators (such as the Adobe Structured Data Validator), you may encounter warnings for certain properties. These are validator limitations, not library bugs — the generated output is valid schema.org JSON-LD and passes Google's Rich Results Test.

datePublished warnings

The following types may trigger a datePublished warning in some validators, despite datePublished being a valid schema.org property inherited from CreativeWork:

• MobileApplication
• Movie
• VacationRental

Recipe optional property warnings

These valid schema.org properties on Recipe may be flagged as "unsupported" by some validators:

• expires
• hasPart
• publication
• ineligibleRegion
• interactionStatistic

These properties are defined on schema.org and are correctly serialized by this library. The warnings come from validators that maintain an incomplete allowlist of properties per type.

Contributing

Contributions are welcome! Please:

1. Fork the repository and create a feature branch.
2. Add or update schema classes in php/src/v1/Schema/ (PHP) or ts/src/schema/ (TypeScript).
3. Write tests in php/test/unit/ (PHP) or ts/test/schema/ (TypeScript).
4. Run composer run cs-fix and composer run test-unit for PHP changes.
5. Run npm run test, npm run build, and npx biome check for TypeScript changes.
6. For TypeScript schema additions, follow the options-object constructor pattern and update barrel exports in ts/src/index.ts.
7. Open a pull request with a clear description of the change.

When adding a new schema type, follow the existing language-specific patterns: PHP classes extend TypedSchema and set A_SCHEMA_TYPE; TypeScript classes extend TypedSchema, set schemaType, and use options-object constructors.

License

MIT — see LICENSE.