Schema Org Api Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require effectiveactivism/schema-org-api
   

   Add the service provider to config/app.php under providers:

   EffectiveActivism\SchemaOrg\Providers\SchemaOrgServiceProvider::class,
   

2. First Use Case: Querying Schema.org Types Use the SchemaOrg facade to fetch a type definition:

   use EffectiveActivism\SchemaOrg\Facades\SchemaOrg;
   
   $personType = SchemaOrg::type('Person');
   dd($personType->properties); // Inspect properties
   

3. Explore the GraphQL Schema The package exposes Schema.org as a GraphQL schema. Start with the root query:

   $query = SchemaOrg::query()
       ->type('Thing')
       ->properties()
       ->get();
   

Implementation Patterns

Core Workflows

1. Type Introspection Dynamically inspect Schema.org types and their relationships:

   $event = SchemaOrg::type('Event');
   $event->subTypes(); // ['Reservable', 'OfferCatalog', ...]
   $event->superType(); // 'Thing'
   

2. Property Validation Validate input data against Schema.org constraints:

   $validator = SchemaOrg::validator('Person');
   $validator->validate([
       'name' => 'John Doe',
       'age' => 30, // Will fail (age is not a valid property for Person)
   ]);
   

3. GraphQL Query Building Construct queries for specific use cases (e.g., SEO metadata):

   $query = SchemaOrg::query()
       ->type('WebPage')
       ->properties(['name', 'description', 'publisher'])
       ->get();
   

4. Integration with Laravel Models Attach Schema.org types to Eloquent models:

   use EffectiveActivism\SchemaOrg\Traits\HasSchemaOrgType;
   
   class BlogPost extends Model
   {
       use HasSchemaOrgType;
   
       protected $schemaOrgType = 'BlogPosting';
   }
   

Integration Tips

• Caching: Cache type definitions for performance:

  $type = SchemaOrg::remember('Person', 60, function () {
      return SchemaOrg::type('Person');
  });
  

• Dynamic Schema Generation: Use the package to auto-generate JSON-LD for views:

  $jsonLd = SchemaOrg::jsonLd($model, 'BlogPosting');
  view()->share('jsonLd', $jsonLd);
  

• API Responses: Serialize API responses with Schema.org validation:

  return response()->json([
      'data' => $validator->validate($request->all()),
  ]);
  

Gotchas and Tips

Pitfalls

1. Type Hierarchy Confusion

   • Schema.org types are hierarchical (e.g., Person extends Thing). Always check superType() and subTypes() to avoid missing inherited properties.
   • Fix: Use SchemaOrg::type('Thing')->properties() to get all possible properties for a type hierarchy.

2. Property Constraints

   • Some properties require specific types (e.g., datePublished must be a DateTime). The validator will throw exceptions for mismatches.
   • Fix: Use SchemaOrg::type('Event')->property('datePublished')->type() to check constraints before validation.

3. GraphQL Schema Limitations

   • The GraphQL layer is read-only. Complex nested queries may not be supported out of the box.
   • Fix: Build queries incrementally and test with SchemaOrg::query()->explain().

4. Performance with Large Datasets

   • Loading all Schema.org types at once can be memory-intensive.
   • Fix: Lazy-load types or use SchemaOrg::type($name, ['load' => 'properties']) to limit loaded data.

Debugging

• Inspect Raw Data:

  $type = SchemaOrg::type('Thing');
  dd($type->toArray()); // Raw data structure
  

• Enable Query Logging:

  SchemaOrg::enableQueryLogging();
  SchemaOrg::query()->type('Event')->properties()->get();
  // Check logs for generated GraphQL queries.
  

Extension Points

1. Custom Type Mappings Override default type definitions in a service provider:

   SchemaOrg::extend('CustomType', function () {
       return SchemaOrg::type('Thing')->mergeProperties([
           'customField' => ['type' => 'string', 'description' => 'Custom field'],
       ]);
   });
   

2. Add Custom Validators Extend validation logic for specific use cases:

   SchemaOrg::validator('Person')->extend('age', function ($attribute, $value, $fail) {
       if ($value < 18) {
           $fail('Age must be 18 or older.');
       }
   });
   

3. Hook into JSON-LD Generation Modify JSON-LD output globally:

   SchemaOrg::macro('jsonLd', function ($model, $type) {
       $jsonLd = parent::jsonLd($model, $type);
       $jsonLd['@context'] = 'https://schema.org';
       return $jsonLd;
   });
   

Config Quirks

• Default Context: The package uses http://schema.org by default. Override in config/schema-org.php:

  'context' => 'https://custom-schema.org',
  

• GraphQL Depth Limit: Nested queries may hit depth limits. Adjust in config:

  'graphql' => [
      'max_depth' => 10,
  ],