# @backref/graphql-to-json-schema

> Transform a GraphQL Schema introspection file to a valid JSON Schema.

Latest version **0.3.1** (published 2020-07-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @backref/graphql-to-json-schema
pnpm add @backref/graphql-to-json-schema
yarn add @backref/graphql-to-json-schema
bun add @backref/graphql-to-json-schema
```

Provides the command `gql2js`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.1 |
| Published | 2020-07-19 |
| First published | 2020-07-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 38.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Mario L Gutierrez |
| Maintainers | mgutz |

## Links

- npm: https://www.npmjs.com/package/@backref/graphql-to-json-schema
- Repository: https://github.com/backref/graphql-to-json-schema
- Homepage: https://github.com/backref/graphql-to-json-schema#readme
- Issues: https://github.com/backref/graphql-to-json-schema/issues
- npm.io page: https://npm.io/package/@backref/graphql-to-json-schema

## Dependencies (7)

- [ajv](https://npm.io/package/ajv.md) ^6.5.0
- [globby](https://npm.io/package/globby.md) ^11.0.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.19
- [graphql](https://npm.io/package/graphql.md) ^15.3.0
- [make-dir](https://npm.io/package/make-dir.md) ^3.1.0
- [commander](https://npm.io/package/commander.md) ^5.1.0
- [functional-json-schema](https://npm.io/package/functional-json-schema.md) 0.0.2-3

## Recent versions

- 0.3.1 (latest) — 2020-07-19
- 0.3.0 — 2020-07-19

## README

# graphql-2-json-schema

Transform a GraphQL Schema introspection file to a valid JSON Schema.

This package adds support for decorators improving the utility of GraphQL schema
as an IDL for everything.

## Decorators

Decorators, aka annotations or attributes in other languages, allows
metadata to be attached to GraphQL schema entities. The decorator metadata
appear as properties in the resulting JSON schema. Decorator metadata can be
used for validations, ACL roles, code generation, form generation ...

The syntax is simple

```shell
# decorator with map value
+go_tag({"json": "id", "db": "id"})

# truthy decorator, empty parens default to true
+read_only()
+read_only(false)

# array
+acl_roles(["session", "admin"])

# string
+go_ident("ID")

# number (int, float, etc)
+form_pos(1)
```

Decorator rules

- MUST be within a quotes `""` description or docstring
- MUST be on its own line
- MUST be preceeded by a `+` symbol to disambiguate against `@` directives
- MUST have valid JSON value within parentheses. An empty parentheses `()`
  is converted to boolean value of `true`.

Decorators example in GraphQL schema

```graphql
type Todo {
  """
  The primary key.

  +read_only()
  +go_ident("ID")
  +go_tag({"db": "id", "json": "id,omitempty"})
  """
  id: String!
  name: String!
  completed: Boolean
}
```

The result JSON schema is enriched with `__decorators` property

```js
Todo: {
    type: 'object',
    properties: {
        id: {
            __decorators: {
                go_ident: "ID",
                go_tag: {db:"id", json: "id,omitempty"},
                read_only: true
            },
            description: 'The primary key',
            type: 'string'
        },
        name: { type: 'string' },
        completed: { type: 'boolean' },
    },
    required: ['id', 'name']
}
```

## Usage

To use the `gql2js` CLI utility, first install the package

```sh
yarn global add @backref/graphql-to-json-schema

# OR
npm install -g @backref/graphql-to-json-schema
```

Running the utility

```shell
# output to STDOUT
gql2js example/example.graphql

# output to file
gql2js example/example.graphql -o example.json

# output to directory (use single quotes)
gql2js 'example/**/*.graphql' -d _temp
```

Programmatic

```sh
yarn add @backref/graphql-to-json-schema
```

```javascript
// node example
const g2j = require('@backref/graphql-to-json-schema');

const text = `
type Todo {
  """
  The primary key.

  +read_only()
  +go_ident("ID")
  +go_tag({"db": "id", "json": "id,omitempty"})
  """
  id: String!
  name: String!
  completed: Boolean
}
`;

const jsonSchema = g2j.parseGraphQL(text);
console.log(JSON.stringify(jsonSchema, null, 2));
```

## License

This package is MIT licensed

Original work by

- [wittydeveloper](https://github.com/wittydeveloper/graphql-to-json-schema)

Enhancements by

- [aldeed](https://github.com/aldeed/graphql-to-json-schema)

---
_Source: https://npm.io/package/@backref/graphql-to-json-schema · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._