Schema.org Blueprints
Uses Schema.org as the blueprint for content architecture and structured data in a Drupal website, providing perfect data structures, pristine APIs (JSON:API), and great SEO (JSON-LD).
schemadotorg
Overview
The Schema.org Blueprints module uses Schema.org as the blueprint for a Drupal website's content architecture and structured data. It installs Schema.org's data from CSV files into Drupal and provides comprehensive tools for mapping Drupal entities to Schema.org types.
This module serves as the core foundation for building semantically structured content in Drupal. It defines Schema.org mapping and mapping type entities, allowing administrators to create entity types and fields based on Schema.org type definitions. The module ensures that Schema.org's naming conventions work seamlessly with Drupal's internal naming conventions (converting camelCase to snake_case and handling character limits).
With 52+ sub-modules providing integrations with contributed modules like Paragraphs, Media, JSON-LD, JSON:API, Metatag, Pathauto, and more, Schema.org Blueprints offers a complete ecosystem for building semantically-rich, SEO-optimized Drupal sites. The module supports both traditional Drupal rendering and headless/decoupled architectures through its comprehensive API support.
Features
- Installs and manages Schema.org types and properties data from CSV files in Drupal database tables
- Defines Schema.org mapping config entities that map Drupal entity types/bundles to Schema.org types
- Defines Schema.org mapping type config entities that provide default settings for each Drupal entity type
- Automatically builds entity types, bundles, and fields from Schema.org type definitions
- Provides configurable naming conventions to convert Schema.org camelCase names to Drupal snake_case with abbreviations for length constraints
- Exposes Schema.org types and properties to other Drupal modules via services and APIs
- Provides Schema.org type entity reference selection plugin for filtering entity references by Schema.org types
- Provides Schema.org type Views filter plugin for filtering views results by Schema.org types
- Supports additional Schema.org mappings (multiple types per entity)
- Integrates with contributed modules including Duration, Entity Browser, Focal Point, Linkit, and Media Library Media Modify
- Provides Drush commands for creating and deleting Schema.org type mappings
- Provides Config Action plugins for creating Schema.org types via Drupal recipes
- Manages reusable JavaScript libraries (jsTree, Mermaid, CodeMirror) for UI components
- 52+ sub-modules for JSON-LD, JSON:API, Paragraphs, Media, Metatag, Pathauto, and more integrations
Use Cases
Building a semantically structured content site
Use Schema.org Blueprints to create content types based on Schema.org types like Article, Event, Organization, Person, and Place. The module automatically creates appropriate fields, configures displays, and ensures your content architecture follows established semantic web standards. This provides better interoperability and understanding of your content's meaning.
Implementing JSON-LD structured data for SEO
Enable the schemadotorg_jsonld sub-module to automatically generate JSON-LD structured data in your page headers. This structured data is recognized by search engines like Google, Bing, and others, improving your site's SEO through rich snippets and enhanced search results. The data is generated based on your Schema.org mappings without additional configuration.
Creating a headless/decoupled Drupal site
Use the schemadotorg_jsonapi sub-module to expose your content through a standardized JSON:API that follows Schema.org conventions. This creates predictable, well-documented API endpoints that frontend developers can consume regardless of your internal Drupal structure, making decoupled architecture implementation straightforward.
Rapidly prototyping content models
Use Drush commands like 'drush schemadotorg:create-type node:Event' to quickly scaffold complete content types with all recommended fields based on Schema.org definitions. This accelerates content modeling by starting from industry-standard type definitions rather than building from scratch.
Building a medical or healthcare website
Leverage Schema.org's extensive medical vocabulary including types like Hospital, Physician, MedicalCondition, Drug, and MedicalProcedure. The module's pre-configured medical type categories and property mappings help build compliant healthcare information sites with proper structured data.
Creating event or education platforms
Use Schema.org types like Event, Course, CourseInstance, EducationalOrganization to build event management or education platforms. The module handles complex relationships like course prerequisites, event schedules, and educational credentials with appropriate field types.
Implementing a recipe or food-related site
The Recipe Schema.org type is extensively configured with properties like recipeIngredient, recipeInstructions, cookTime, prepTime, nutrition, and suitableForDiet. Combined with JSON-LD output, your recipes will be eligible for Google's recipe rich snippets.
Managing complex content hierarchies with Paragraphs
Use schemadotorg_paragraphs to create paragraph types for Schema.org intangible types like PostalAddress, ContactPoint, OpeningHoursSpecification, and HowToStep. These can be embedded within parent content types to model complex nested Schema.org structures.
Tips
- Enable the Schema.org Blueprints Help module (schemadotorg_help) first to access comprehensive documentation for all sub-modules at /admin/help
- Use the Schema.org Blueprints Report module (schemadotorg_report) to browse and search Schema.org types and properties with their Drupal name conversions
- Start with the mapping_set module to create related types together (e.g., Person + Organization + Place for a directory)
- Configure default properties at the type level (/admin/config/schemadotorg/settings/types) before creating mappings to ensure consistent field sets
- Use the !propertyName syntax in default properties to explicitly remove inherited properties you don't need
- The Schema.org type categories help organize types in the UI - customize colors and groupings to match your site's needs
- For headless/decoupled sites, enable both schemadotorg_jsonapi and schemadotorg_jsonld to get consistent APIs and structured data
- Field weights in properties settings control the order fields appear in forms and displays - set these before creating mappings
- Use the schemadotorg_diagram module to visualize Schema.org type relationships and validate your content architecture
- The additional_mappings feature lets you add multiple Schema.org types to a single Drupal bundle for complex content like a Person who is also an Author
Technical Details
Admin Pages 8
/admin/config/schemadotorg
Main administrative landing page for Schema.org Blueprints configuration. Provides access to mappings, mapping types, and settings.
/admin/config/schemadotorg/mappings
Lists all mappings from Drupal entity types to Schema.org types. Shows the entity type, bundle, and mapped Schema.org type for each mapping. Allows editing and deleting existing mappings.
/admin/config/schemadotorg/types
Lists mapping types with default settings for available Drupal entity types. Each mapping type defines how Schema.org types are mapped to a specific Drupal entity type (node, user, media, paragraph, etc.).
/admin/config/schemadotorg/settings
Main settings landing page providing access to General, Types, Properties, and Names configuration sub-pages.
/admin/config/schemadotorg/settings/general
Configure general settings for the Schema.org Blueprints module including requirements checking and Schema.org data source.
/admin/config/schemadotorg/settings/types
Configure default settings for Schema.org types including default type definitions, properties, field types, and categories.
/admin/config/schemadotorg/settings/properties
Configure default settings for Schema.org properties including field definitions, formatter settings, field types, weights, and ignored properties.
/admin/config/schemadotorg/settings/names
Configure how Schema.org's naming conventions for types and properties are converted to Drupal's naming conventions for bundles and fields. Schema.org uses camelCase while Drupal uses snake_case with 32 character limits.
Permissions 1
Hooks 7
hook_schemadotorg_property_field_type_alter
Alter the field types available for a Schema.org property. Allows modules to add or reorder field type options when mapping properties.
hook_schemadotorg_property_field_prepare
Prepare a property's field data before the Schema.org mapping form is displayed. Allows customization of default field values.
hook_schemadotorg_bundle_entity_alter
Alter bundle entity type values before the entity is created. Allows modification of entity type properties.
hook_schemadotorg_property_field_alter
Alter field storage and field values before fields are created. Allows comprehensive customization of field configuration, widgets, and formatters.
hook_schemadotorg_mapping_defaults_alter
Alter Schema.org mapping entity default values. Allows modification of mapping defaults before they are used.
hook_schemadotorg_mapping_apply
Respond when a Schema.org mapping is being applied (saved). Allows modules to perform additional actions when mappings change.
hook_ENTITY_TYPE_postsave
Respond after a Schema.org mapping entity is inserted or updated. Used for adding additional mappings after the main mapping is saved.
Drush Commands 5
drush schemadotorg:create-type
Create Schema.org types by specifying entity type and Schema.org type pairs. Creates the Drupal entity bundle and all mapped fields.
drush schemadotorg:delete-type
Delete Schema.org types and optionally their associated entities and fields.
drush schemadotorg:update-schema
Update Schema.org data by reimporting from CSV files. Refreshes the schemadotorg_types and schemadotorg_properties database tables.
drush schemadotorg:download-schema
Download the latest Schema.org CSV data from schema.org. Maintainer command for updating bundled data files.
drush schemadotorg:translate-schema
Extract translatable strings from Schema.org CSV data for localization. Maintainer command.
Troubleshooting 5
Schema.org uses long property names that may exceed Drupal's 32-character limit for field names. Configure abbreviations, prefixes, and suffixes at /admin/config/schemadotorg/settings/names to control how names are shortened. Add custom_names mappings for specific problematic properties.
The module checks for recommended integrations. Either install the recommended modules (Duration Field, Entity Browser, Focal Point, Linkit) or disable the check at /admin/config/schemadotorg/settings/general by unchecking 'Check for recommended modules'.
When using Schema.org entity reference selection, ensure target bundles have Schema.org mappings. The selection handler filters by Schema.org types, so unmapped bundles won't appear. Check the property's rangeIncludes and create mappings for desired types.
Check if the property is in the ignored properties list at /admin/config/schemadotorg/settings/properties. Some technical or rarely-used properties are hidden by default to simplify the UI. Remove them from the ignored list if needed.
Ensure the format is correct: entity_type:SchemaType (e.g., node:Article). The Schema.org type must be a valid type from schema.org. Check that no existing mapping conflicts with the requested type.
Security Notes 4
- The 'administer schemadotorg' permission is powerful and should only be granted to trusted administrators as it allows creating entity types and fields
- When using JSON-LD output, be aware that structured data is publicly visible and should not contain sensitive information
- Entity reference selection by Schema.org type respects entity access controls but ensure proper view permissions are configured
- The JSON:API integration follows JSON:API module's access controls - configure resource access appropriately for your use case