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-es-mapping -S
• yarn: yarn add json-schema-to-es-mapping

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

Date-as-a-scalar

You can add your own scalar types via the config. We assume you are using Date by default.

Sample date scalar: graphql-iso-date

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

Author

2018 Kristian Mandrup (CTO@Tecla5)

License

MIT