Schemata

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.

What has a Schema?

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.

Where is the Schema?

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.

Requirements

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.

Architecture

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.

Usage

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)

Request

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).

Programmatically

// 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);

Related Projects

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.

Contribute

• 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

URLs

• Homepage
• Development

Maintainers

Adam Ross a.k.a. Grayside

Contributors

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.

F.A.Q.

Will there be a Drupal 7 backport?

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.

Why not use some other module?

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.