graphql-type-json

graphql-type-json provides a ready-made JSON scalar type for GraphQL.js, letting schema authors accept and return arbitrary JSON values or JSON objects without hand-writing a custom scalar. It ships both a permissive GraphQLJSON scalar for any JSON-serializable value and a stricter GraphQLJSONObject scalar that only accepts objects, covering the two most common cases teams run into when a field genuinely needs an untyped payload.

The package is a small, focused utility rather than a framework: you import the scalar, wire it into your schema (programmatically or via SDL with graphql-tools), and GraphQL.js handles serialization, parsing, and literal parsing for you. It has been a de facto standard in the GraphQL.js ecosystem for years, with wide adoption across servers built on Apollo Server, express-graphql, and similar tooling.

What You Get

• A GraphQLJSON scalar type that serializes, parses, and validates any JSON-serializable value (strings, numbers, booleans, arrays, objects, null)
• A GraphQLJSONObject scalar type that restricts values to JSON objects, rejecting arrays and primitives at the type level
• Full support for GraphQL literal parsing, so JSON values can appear directly in query documents, not just as variables
• TypeScript type definitions bundled with the package for both scalars
• Both CommonJS and ES module builds, plus SDL-friendly resolver map usage with graphql-tools

Common Use Cases

• Exposing a legacy or third-party API’s loosely-typed JSON payload through a GraphQL field without modeling every possible shape
• Storing and returning flexible metadata blobs (e.g. user preferences, feature flags, arbitrary config) attached to a typed GraphQL entity
• Bridging a REST endpoint that returns free-form JSON into a GraphQL schema during incremental migration

Under The Hood

Architecture: The package is a thin wrapper around GraphQL.js’s GraphQLScalarType API. src/index.js defines two scalar instances by supplying serialize, parseValue, and parseLiteral functions; there is no class hierarchy, no build-time codegen, and no runtime state beyond the two exported constants. parseLiteral recursively walks the GraphQL AST (parseLiteral/parseObject helpers) to support JSON literals embedded directly in query documents, which is the one piece of nontrivial logic in the codebase.

Tech Stack: Written in ES2015+ JavaScript, compiled with Babel to both CommonJS (lib/) and ES module (es/) output for dual consumption. The only runtime dependency is a peer dependency on graphql (>=0.8.0); dev dependencies cover Babel, ESLint, Prettier, Jest, and dtslint for type-definition testing.

Code Quality: A single test/index.test.js file exercises both scalars’ serialize/parseValue/parseLiteral paths, including error cases for non-object values passed to GraphQLJSONObject. ESLint and Prettier are enforced via lint-staged pre-commit hooks. The code is small enough (roughly 70 lines) that naming and structure are straightforward; there is no dedicated error-handling layer beyond throwing TypeError for invalid JSONObject values.

API Design: The public surface is exactly two exports (GraphQLJSON default export, GraphQLJSONObject named export), usable with zero configuration — import and drop into a schema’s field type or resolver map. TypeScript definitions are bundled so consumers get type safety without an extra @types install. The README documents both programmatic-schema and SDL/graphql-tools usage patterns, keeping the learning curve minimal.