GraphQL JSON

GraphQL JSON is a powerful tool that helps you create GraphQL schemas using JSON in runtime. With an input schema based on the GraphQL type API, it should feel familiar to most users.

This package offers a TypeScript-typed solution for creating schemas for your GraphQL server, allowing you to take advantage of TypeScript to avoid errors. At the same time, it preserves the flexibility that GraphQL offers, enabling you to shape your schema to your liking.

The main goal of this package is to simplify the process of constructing GraphQL schemas. It helps you eliminate unnecessary clutter, making it easier to understand and modify your schemas. This way, you can reduce errors and build a reliable GraphQL API without the downsides of the GraphQL Types API or the GraphQL Schema Language.

Installation

You can install graphql-json by running one of the commands below:

# npm
npm install @gwesseling/graphql-json

# yarn
yarn add @gwesseling/graphql-json

# pnpm
pnpm install @gwesseling/graphql-json

Usage

The usage of this package is straightforward.

import createSchema from "@gwesseling/graphql-json";

const server = new ApolloServer({
    schema: createSchema(schema, options),
});

For a complete input examples, please refer to the examples folder. This folder contains a comprehensive JSON input, as well as the resulting output generated by the tool.

Schema

Base type

| Property | Description | Type | Required | | ----------- | ------------------------ | --------------------- | -------- | | description | description of your type | string | No | | type | The related GraphQL type | GraphQLType | No |

Types

| Type | Description | | ---------------------- | --------------------------- | | GraphQLEnumType | A GraphQL Enum type | | GraphQLObjectType | A GraphQL Object type | | GraphQLScalarType | A GraphQL Scalar type | | GraphQLUnionType | A GraphQL Union type | | GraphQLInputObjectType | A GraphQL Input object type | | GraphQLInterfaceType | A GraphQL Interface type | | name | Named type |

Named types

| Type | Description | | --------- | ----------------------------- | | enum | A GraphQL Enum type | | object | A GraphQL Object type | | scalar | A GraphQL Scalar type | | union | A GraphQL Union type | | input | A GraphQL Input object type | | interface | A GraphQL Interface type | | id | A GraphQL Id scalar type | | string | A GraphQL String scalar type | | int | A GraphQL Integer scalar type | | float | A GraphQL Float scalar type | | boolean | A GraphQL Boolean scalar type | | name | Named type |

Input types

| Type | Description | | ---------------------- | --------------------------- | | GraphQLEnumType | A GraphQL Enum type | | GraphQLScalarType | A GraphQL Scalar type | | GraphQLInputObjectType | A GraphQL Input Object type | | name | Named type |

Output types

| Type | Description | | -------------------- | -------------------------- | | GraphQLEnumType | A GraphQL Enum type | | GraphQLObjectType | A GraphQL Object type | | GraphQLScalarType | A GraphQL Scalar type | | GraphQLUnionType | A GraphQL Union type | | GraphQLInterfaceType | A GraphQL Interface type | | name | Named type |

Enum type

| Property | Description | Type | Required | | -------- | ------------------------------ | -------- | -------- | | values | An Object map with Enum values | Object | Yes |

Object type

| Property | Description | Type | Required | | ---------- | ------------------------------------------------------------ | ---------------------------------------------------- | -------- | | interfaces | Array of Interfaces to implement | Array (string or GraphQLInterface) | No | | fields | An Object map of Fields | Field | Yes | | isTypeOf | A function that helps resolve the GraphQL type of the Object | (value: any, info?: GraphQLResolveInfo) => boolean | No |

Input object type

| Property | Description | Type | Required | | -------- | ----------------------- | --------------------------------- | -------- | | fields | An Object map of Fields | Field | Yes |

Union type

| Property | Description | Type | Required | | ----------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | types | Types to combine as an Union type | GraphQLObjectType or string | Yes | | resolveType | A function that helps resolve the GraphQL type of the Object | (value: TSource, context: TContext, info: GraphQLResolveInfo, abstractType: GraphQLAbstractType, ) => PromiseOrValue<string / undefined> | No |

Interface type

| Property | Description | Type | Required | | ----------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | interfaces | Array of Interfaces to implement | Array (string or GraphQLInterface) | No | | fields | An Object map of Fields | Field type | Yes | | resolveType | A function that helps resolve the GraphQL type of the Object | (value: TSource, context: TContext, info: GraphQLResolveInfo, abstractType: GraphQLAbstractType, ) => PromiseOrValue<string / undefined> | No |

Scalar type

| Property | Description | Type | Required | | -------------- | --------------------------------------- | -------------------------------------------------------------------------- | -------- | | specifiedByURL | Scalar specification URL | string | No | | serialize | Function to serialize the value to JSON | (outputValue: unknown) => TExternal | No | | parseValue | Function to parse the value | (inputValue: unknown) => TInternal; | No | | parseLiteral | Function to partse the hard-coded AST | (valueNode: ValueNode, variables?: Maybe<ObjMap<unknown>>) => TInternal; | No |

Sub types

Field type

| Property | Description | Type | Required | | ----------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- | ------------------ | | type | Type of the Field | Output type or string | No* | | list | List item type | List type | No* | | required | Whenever the Field is non-nullable | boolean | No (default false) | | args | Object map of arguments | Argument type | no | | resolve | Resolves Field data | (source: TSource, args: TArgs, context: TContext, info: GraphQLResolveInfo) => TResult; | No | | subscribe | Subscribe to Field | (source: TSource, args: TArgs, context: TContext, info: GraphQLResolveInfo) => TResult; | No | | deprecationReason | Reason why Field is deprecated | string | No |

* Type or List is required.

Field list type

| Property | Description | Type | Required | | -------- | ---------------------------------- | ---------------------------------------- | -------- | | type | GraphQLList type | Output Type or string | Yes | | required | Whenever the Field is non-nullable | boolean | No |

Field argument

| Property | Description | Type | Required | | ----------------- | --------------------------------- | -------------------------------------- | -------- | | type | Type of the argument | Input type or string | No* | | list | List item type | List type | No* | | deprecationReason | Reason why argument is deprecated | string | No |

* Either type or list is required.

Field argument item type

| Property | Description | Type | Required | | -------- | ---------------------------------- | -------------------------------------- | -------- | | type | GraphQLList type | Input type or string | Yes | | required | Whenever the field is non-nullable | boolean | No |

Input object field type

| Property | Description | Type | Required | | ----------------- | ---------------------------------- | ------------------------------------------ | -------- | | type | Type of the Field | Input type or string | No* | | list | List item type | Item type | No* | | required | Whenever the Field is non-nullable | boolean | No | | defaultValue | Default Field value | unknown | No | | deprecationReason | Reason why argument is deprecated | string | No |

* Type or List is required.

Input object field item type

| Property | Description | Type | Required | | -------- | ---------------------------------- | -------------------------------------- | -------- | | type | GraphQLList type | Input type or string | Yes | | required | Whenever the Field is non-nullable | boolean | No |

Options

| Property | Description | Type | Required | | ----------------- | --------------------------------------------------------------------------------- | --------------------------------------- | -------- | | context | Pre-fill the context with custom types that graphql-json can use to resolve types | object | No | | description | Schema description | string | No | | types | Schema description types | Array of GraphQLNamedType or string | No | | directives | Schema directives | Array of GraphQLDirective | No | | extensions | Schena extension | GraphQLSchemaExtensions | No | | astNode | Schema astNode | SchemaDefinitionNode | No | | extensionASTNodes | Schema extensionASTNodes | SchemaExtensionNode | No |