graphql-lint-rules 2.0.1
Install from the command line:
Learn more about npm packages
$ npm install @pinterest/graphql-lint-rules@2.0.1
Install via package.json:
"@pinterest/graphql-lint-rules": "2.0.1"
About this version
This is a set of zero-dependency rules to be used with the graphql-schema-linter
package.
These rules are based on schema conventions we have established at Pinterest.
For instance, to package with your project, run:
npm install -D @pinterest/graphql-lint-rules
Or, if you want to use these rules locally across multiple projects, run:
yarn global add @pinterest/graphql-lint-rules
Add the following to your configuration file for graphql-schema-linter
:
// The exact format here depends on what configuration format (JSON or JavaScript) you use
"customRulePaths": ["/path/to/npm_modules/@pinterest/graphql-lint-rules/rules/*.js"]
If you prefer, pass --custom-rule-paths '/path/to/npm_modules/@pinterest/graphql-lint-rules/rules/*.js'
to graphql-schema-linter
instead.
Finally, add the names of the rules you want to lint to the rules
array of your config (or --rules
flag)
For example:
"rules": [
"composite-fields-are-nullable"
]
When a field has a composite GraphQL type (object, interface, union), it must not be declared as a non-null field.
Composite fields are more often tied to a resolver that needs to fetch some additional data than are scalar fields. Any failure that results from that data fetch will cause a null
value to bubble up the query tree unless the field is marked as nullable.
While it is possible to change a nullable field to non-null in schema updates, the reverse is a breaking change. The "safe" default behavior is to have these fields be nullable.
Caleb Meredith has written a good summary of issues around nullability.
The pageInfo
field is specified by the Relay cursor connections specification as a non-null field, and therefore violates this rule. Since it's more important to follow the spec than this rule, fields that use the PageInfo
type are skipped.
As many schemas will have a nonzero number of exceptions to this rule, fields can be marked with an @allowNonNull
decorator (which you must add to your schema) to skip this rule as well. Standard graphql-schema-linter
overrides will work as well.
Also, a list of exceptions can be added to the rulesOptions
, so that entire scenarios can be excluded at once.
"rulesOptions": [
"composite-fields-are-nullable": {
"exceptions": [
"ErrorInfo",
]
},
]
This rule will validate that object type field and interface type field names are camel-cased or start with an underscore.
GraphQL field names should be valid GraphQL identifiers. For field names that have numeric names, one can use the approach to add an underscore to the start of the field name to make it a valid GraphQL identifier. This rule checks that field names follow the camelCase format, but also allowing for them to start with an underscore.
When a type implements the Node
interface, it must contain a non-nullable string named entityId
.
For cross-compatibility with other APIs, our model types need to expose the primary identifier that can be used to identify the object across services. We do not, however, want to use Node
's id
field for this identifier, as clients expect id
to be globally unique across model and type (which our primary identifier is not). By enforcing the presence of entityId
, we ensure there is a field to expose both, without changing the standard Node
interface and still allowing for exceptional cases.
This rule will validate that types that end in ConnectionContainer
return types that end in Connection
.
This rule will validate the schema adheres to section 2 (Connection Types) of the Relay Cursor Connections Specification.
More specifically:
- Only object type names may end in
Connection
. These object types are considered connection types. - Connection types must have a
edges
field that returns a list type. - Connection types must have a
pageInfo
field that returns a non-nullPageInfo
object.
This is basically the same validation done in graphql-schema-linter
, but with some extra validation:
-
edges
field must return a list type of an object type that ends inEdge
.
This rule will validate the schema adheres to section 3 (Edge Types) of the Relay Cursor Connections Specification.
More specifically:
- Edge types must have a
cursor
field that returns a type that serializes as aString
. - Edge types must have a
node
field return either aScalar
,Enum
,Object
,Interface
,Union
, or a Non-Null wrapper around one of those types.
Also, it adds some validation regarding Pinterest-specific rules:
- Only edge type names may end in
Edge
. These object types are considered edge types.
See CONTRIBUTING.md
.