Facilitate generation of schema definitions of Drupal 8 data models.
A schema is a declarative description of structured data that prescribes the rules for how that data can be created. Schemas are commonly used to provision relational storage, to generate forms or other user interfaces, to generate client library code, or to validate data.
Schemata supports the creation of provider modules that create schemas to describe the different entities in a Drupal site (such as Nodes, Taxonomy Terms, and Users) as they are rendered in Drupal REST responses. This project ensures your Drupal site is able to deliver self-documenting machine descriptions of your API payloads, driven by the same configuration that Drupal uses to build forms and validate entities.
In addition to the more abstract developer module named "Schemata", there is a reference implementation of a schema provider: Schemata JSON Schema, which provides JSON Schema support to define entities delivered in Drupal Core's JSON and HAL JSON REST formats, and the contrib module and format JSON API.
All Content Entity Types and Bundles have a schema automatically via the Schemata module. Core support for this kind of structured description of configuration does not exist yet.
Schemata are accessed via regular routes. Once enabled, Schemata resources are
found at /schemata/{entity_type}/{bundle?}. These resources are dynamically
generated based on your entity definitions, which means any change to fields on
an Entity will automatically be reflected in the schema.
Drupal 8.3 is required for Schemata's generated schemas to validate your REST responses.
Schemata-the-module is a dependency for the sub-modules of the project:
- Schemata JSON Schema: A serializer which processes Schemata schema objects into JSON Schema v4. Describes the output of content entities via the core JSON, HAL and JSON API serializers.
From a "product" standpoint, JSON Schema is the value, and Schemata the technical dependency. Only install Schemata if you plan to install a Schema provider module that depends on it.
The Schemata project contains the Schemata and Schemata JSON Schema modules.
The Schemata module provides routes to retrieve a serialized, machine-readable
schema. The schemas are assembled dynamically leveraging the
Typed Data API and other site configuration.
The schema for each entity type (and bundle) is exposed in the manner of a
REST resource, accessible via GET requests designating the appropriate _format
parameter to select a schema type and _describes to target a particular entity
representation format supported by Drupal REST.
In order to serialize the Schema object, the serializer must be able to support implementations of the Drupal\schemata\Schema\SchemaInterface class. At this time, the only serializer support for Schemata is within this project, you can see an example of this in the packaged submodule Schemata JSON Schema.
You can obtain the schema either making an HTTP request or by using the programmatic API.
Each schema type format should be contained in its own module. Enable the module for the format that you need first. For instance:
drush en -y schemata_json_schema
Finally you need to grant permission to access the data models to roles that
need it. (access schemata data models)
Create a request against
/schemata/{entity_type}/{bundle}?_format={output_format}&_describes={described_format}
For instance:
/schemata/node/article?_format=schema_json&_describes=hal_json/schemata/user?_format=schema_json&_describes=api_json(omit the bundle if the entity type has no bundles).
// Input variables.
$entity_type_id = 'node';
$bundle = 'article';
$output_format = 'schema_json';
$described_format = 'api_json';
// Services.
$schema_factory = \Drupal::service('schemata.schema_factory');
$serializer = \Drupal::service('serializer');
// Generate a Schema object.
$schema = $schema_factory->create($entity_type_id, $bundle);
// Render the schema as a string conforming to the selecting schema type.
$format = $output_format . ':' . $described_format;
$serializer->serialize($schema, $format);Use the Docson module to visualize the JSON Schemas generated by the Schemata module.
Use the OpenAPI module to generate a Swagger v2 API definition specification, which can in turn be used by ecosystem of Swagger-based tools. For example, the Swagger Tools page and ReDoc.
- Security reports should follow [Drupal.org security reporting procedures] (https://www.drupal.org/node/101494).
- Other bugs and issues should be filed in the Issue Queue
- Code contributions should be submitted as a Pull Request in Github
Adam Ross a.k.a. Grayside
Creation of this module was sponsored by Norwegian Cruise Line.
Fubhy's work on GraphQL was a great help in early architecture of this project. Thank you to Fubhy and the GraphQL sponsors.
This module can be summarized as follows:
A Drupal 8 subsystem (routing) and a Symfony subsystem (Serialization) use a touchy Drupal 8 subsystem (Typed Data) to describe the output of another Drupal 8 subsystem (Entity).
It gets worse--the use cases of this module are most applicable when said entity output comes by way of the routing and Serialization systems.
It does not make sense to discuss a backport unless you first backport large swathes of Drupal 8.
Self Documenting REST API produces webpage reports about REST resources on the site. This project might eventually compete with that if it builds out support for the Swagger specification.
Field Report enhances the core reports about fields and content types. This has some similarity with this project, but the reports provided by Field Report are for people orienting on a site. This project produces schemas that can be used for machine integrations or feeding into other report generation systems.