Introducing Schema Policy in Hive

We are thrilled to announce that Hive got a new, shiny feature: Schema Policy 🎉

As your GraphQL API and schema grow, tasks such as enforcing best practices, deciding on schema design, and collaborating with other teams become more complicated.

We have learned from our experience of building and maintaining many GraphQL APIs over the years that the ability to scale and evolve your API is an important goal. Therefore, we have introduced a new feature in Hive that enables developers to easily lint, verify, and enforce best practices across the entire GraphQL API.

With a simple dashboard configuration, you can enforce the following:

1. Naming conventions (e.g type User instead type user), order of appearance (e.g field name should come after field age), and enum value style (e.g VALUE instead of Value).
2. Require descriptions for specific elements in your GraphQL schemas (e.g a type or a field), and even require a specific style for your descriptions (inline using " ... ", block """ ... """ and even forbid # ... ).
3. Deprecation rules for enforcing a reason for every deprecation, and even a deprecation date.
4. A set of rules to enforce Relay-style GraphQL schema: pagination inputs, Connection types, PageInfo and Node interfaces.
5. Enforce @oneOf structure the right way (by ensuring response structure and directives usage)
6. And +20 more rules you can customize!

Gradual Adoption

During the GraphQL schema check process, policies are executed and evaluated.

You can use this mechanism to ensure that your schema is fully compatible and adhere the schema policies, before running the publish flow and update the schema in the registry.

Each rule can be configured to trigger either a warning or an error.

A warning will be printed as CLI output, while an error will allow you to reject and fail the schema check. This way, you can introduce new policy rules and gradually without breaking your existing pipelines.

Organization/project Level

The GraphQL schema policies are defined at the organization level, and applied to all projects and targets.

You can enable Policy override for projects, and either disable or modify specific policy rules defined at the organization level.

Open-Source under the Hood

The schema policies feature is powered by GraphQL-ESLint, which is another project built and maintained by The Guild. We are using a subset of this feature, specifically designed for linting GraphQL schemas.

With GraphQL-ESLint, you can easily integrate GraphQL into ESLint, and lint GraphQL schemas, operations, and the combination of the two in a full-stack project. You can also build custom rules to enforce specific GraphQL schema designs.

We invite all members of Hive and the GraphQL community to collaborate and improve GraphQL-ESLint by sharing new use-cases and best practices. Rules and customizations added to GraphQL-ESLint will be available quickly as part of Hive.

How to Use Schema Policy?

You can use Policy today with your existing GraphQL-Hive projects. Documentation is also available.

After enabling Policy and rules for your organization or project, try performing a GraphQL schema check to execute the policy check.