JSON Schema to GraphQL types with decorators

Convert JSON schema to GraphQL types (string) including GraphQL transforms/directives (decoratots).

Quick start

• npm: npm install json-schema-to-graphql-types-decorated -S
• yarn: yarn add json-schema-to-graphql-types-decorated

Use

const schema = {
  $schema: "http://json-schema.org/draft-07/schema#",
  $id: "http://example.com/person.schema.json",
  title: "Person",
  description: "A person",
  type: "object",
  properties: {
    id: {
      type: "string",
      generated: true,
      unique: true
    },
    name: {
      description: "Name of the person",
      type: "string",
      graphql: {
        decorators: {
          connection: {
            name: "UserNames"
          }
        }
      }
    },
    age: {
      description: "Age of person",
      type: "integer",
      required: true
    },
    money: {
      description: "Money in pocket",
      type: "number"
    },
    accounts: {
      description: "Bank accounts",
      type: "array",
      items: {
        type: "Account"
      }
    }
  },
  required: ["name"]
};

const { buildTypes } = require('json-schema-to-graphql-types-decorated')
const mapping = buildTypes(schema);

console.log({
  mapping
});

Will output the following GraphQL types (as a raw indented text)

type Person {
  id: ID!
  name: String! @connection(name: "UserNames")
  age: Int!
  money: Float
  accounts: [Account]
}

Using config object (see below)

const mapping = buildTypes(schema, config);

console.log({
  mapping
});

Supporting transforms (decorators)

Add transforms/directives for GraphQL types in a declarative way so they can be included in the generated types.

Allow supplying an extra config object with meta data for directives to be merged into output

{
  decorators: {
    Cart: {
      client: true
    }
    User: {
      email: {
        unique: true
      }
    },
    Post: {
      blog: {
        connection: {
          name: 'BlogPosts'
        }
      }
    }
  }
}

Using meta data in JSON schema

StackOverflow: json-schema-additional-metadata

"You don't have to do anything special to use additional metadata keywords. You can just use them. In JSON Schema it is not an error to include undefined keywords."

So the decorators can also be supplied via a graphql entry directly in the JSON schema as follows:

properties: {
  blog: {
    type: 'string'
    graphql: {
      decorators: {
        connection: {
          name: 'BlogPosts'
        }
      }
    }
  },
}

You can also include decorators entry directly as follows:

properties: {
  blog: {
    type: 'string'
    decorators: {
      connection: {
        name: 'BlogPosts'
      }
    }
  },
}

Customization

You can pass an extra configuration object with specific rules for ES mapping properties that will be merged into the resulting mapping.

const config = {
  _meta_: {
    types: {
      date: "Date", // to use custom Date scalar
      json: "JSON" // to use custom JSON scalar
    }
  }
};

const { buildMapping } = require("json-schema-to-es-mapping");
const mapping = buildMapping(schema, config);

Supporting Scalars

Please see GraphQL scalar type and its input and result coercion

Date scalar

• Date as a scalar
• graphql-iso-date

You can customize the output to use your own scalar types via config._meta_.types. The builder (generator) currently assumes you are using the Date scalar by default.

GraphQL transforms

Amplify

Amplify GraphQL transforms

• @model
• @auth
• @connection
• @searchable

Also see graphql-transform-tutorial

type Post @model {
  id: ID!
  title: String!
  blog: Blog @connection(name: "BlogPosts")
  comments: [Comment] @connection(name: "PostComments")
}

Prisma

Prisma

type User {
  id: ID! @unique
  age: Int
  email: String! @unique
  name: String!
  accessRole: AccessRole
  posts: [Post!]!
}

Apollo

Apollo has a @client directive for Apollo Link State

Adding the @client directive to a field is how Apollo Link knows to resolve your data from the Apollo cache instead of making a network request. This approach is similar to other Apollo Link APIs, such as apollo-link-rest, which uses the @rest directive to specify fields that should be fetched from a REST endpoint.

const getUser = gql`
  query getUser($id: String) {
    user(id: $id) {
      id
      name
      cart @client {
        product {
          name
          id
        }
      }
    }
  }
`;

Thanks to the power of directives and Apollo Link, you’ll (soon) be able to request @client data, @rest data, and data from your GraphQL server all in one query!

Alternatives

• graphql-to-json-schema GraphQL Schema to JSON Schema
• json-schema-to-graphql-types
• jsonschema-to-graphql

Testing

Uses jest for unit testing.

Currently not well tested. Please help add more test coverage :)

TODO

Add support for enum type, see How to design GraphQL queries and mutations: enum type

The enum type is the second type in the GraphQL specification that can be used as a primitive value.

enum TaskStateEnum {
  assigned
  unassigned
  inProgress
}

Author

2018 Kristian Mandrup (CTO@Tecla5)

License

MIT