Docsx-graphql ReferenceQuick Start

X-GraphQL Quick Start Guide

Get started with JSON Schema x GraphQL conversions in under 5 minutes.

Table of Contents

Installation

Node.js

npm install json-schema-x-graphql

Rust

[dependencies]
json-schema-x-graphql = "2.0.0"

CLI Tools

# Install Rust CLI globally
cargo install json-schema-x-graphql --features cli
 
# Or use Node.js CLI via npx
npx json-schema-x-graphql --help

Basic Usage

1. Simple Type Conversion

JSON Schema → GraphQL

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "x-graphql-type-name": "User",
  "properties": {
    "id": {
      "type": "string",
      "x-graphql-field-type": "ID!"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["id", "name"]
}

Converts to:

type User {
  id: ID!
  name: String!
  email: String
}

2. Using the Converter (Node.js)

import { Converter, ConversionDirection } from "json-schema-x-graphql";
 
const converter = new Converter();
 
// JSON Schema to GraphQL
const jsonSchema = `{
  "type": "object",
  "x-graphql-type-name": "Product",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" }
  }
}`;
 
const graphql = converter.convert(
  jsonSchema,
  ConversionDirection.JsonSchemaToGraphQL,
);
 
console.log(graphql);
// Output:
// type Product {
//   id: String
//   name: String
// }

3. Using the Converter (Rust)

use json_schema_x_graphql::{Converter, ConversionDirection};
 
fn main() {
    let converter = Converter::new();
 
    let json_schema = r#"{
        "type": "object",
        "x-graphql-type-name": "Product",
        "properties": {
            "id": { "type": "string" },
            "name": { "type": "string" }
        }
    }"#;
 
    let graphql = converter
        .convert(json_schema, ConversionDirection::JsonSchemaToGraphQL)
        .unwrap();
 
    println!("{}", graphql);
}

Common Patterns

Non-Null Fields

Make a field required in GraphQL:

{
  "properties": {
    "id": {
      "type": "string",
      "x-graphql-field-non-null": true
    }
  }
}
type MyType {
  id: String!
}

Arrays and Lists

Define list types:

{
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "x-graphql-field-type": "[String!]!"
    }
  }
}
type MyType {
  tags: [String!]!
}

Custom Field Names

Override default field name conversion:

{
  "properties": {
    "user_id": {
      "type": "string",
      "x-graphql-field-name": "userId"
    }
  }
}
type MyType {
  userId: String
}

Interfaces

Define GraphQL interfaces:

{
  "type": "object",
  "x-graphql-type-name": "Node",
  "x-graphql-type-kind": "INTERFACE",
  "properties": {
    "id": {
      "type": "string",
      "x-graphql-field-type": "ID!"
    }
  }
}
interface Node {
  id: ID!
}

Implementing Interfaces

{
  "type": "object",
  "x-graphql-type-name": "User",
  "x-graphql-implements": ["Node"],
  "properties": {
    "id": {
      "type": "string",
      "x-graphql-field-type": "ID!"
    },
    "name": {
      "type": "string"
    }
  }
}
type User implements Node {
  id: ID!
  name: String
}

Unions

Define union types:

{
  "oneOf": [{ "$ref": "#/definitions/User" }, { "$ref": "#/definitions/Post" }],
  "x-graphql-type-name": "SearchResult",
  "x-graphql-type-kind": "UNION",
  "x-graphql-union-types": ["User", "Post"]
}
union SearchResult = User | Post

Apollo Federation

Add federation directives:

{
  "type": "object",
  "x-graphql-type-name": "User",
  "x-graphql-federation-keys": ["id"],
  "properties": {
    "id": {
      "type": "string",
      "x-graphql-field-type": "ID!"
    },
    "email": {
      "type": "string",
      "x-graphql-federation-shareable": true
    }
  }
}
type User @key(fields: "id") {
  id: ID!
  email: String @shareable
}

CLI Tools

Validate Schemas

# Validate JSON Schema files
jxql validate json-schema path/to/schema.json
 
# Validate GraphQL SDL files
jxql validate graphql path/to/schema.graphql
 
# Recursive validation
jxql validate json-schema ./schemas -r
 
# Strict mode with detailed output
jxql validate json-schema schema.json -s --format json

Convert Files

# Convert JSON Schema to GraphQL
jxql convert -i schema.json -o schema.graphql
 
# Convert GraphQL to JSON Schema
jxql convert -i schema.graphql -o schema.json --direction graphql-to-json
 
# Batch conversion
jxql convert -i ./schemas -o ./output -r

Run Benchmarks

# Node.js
npm run benchmark
 
# Rust
cargo bench

Next Steps

Learn More

Advanced Topics

  1. Federation Setup

  2. Performance Optimization

    • Enable caching for better performance
    • Configure validation options
    • See benchmark results in CI

  3. Custom Type Mappings

    • Override default type conversions
    • Add custom scalar types
    • Configure naming conventions

Examples

Check out the complete examples in:

  • converters/test-data/x-graphql/ - Test schemas with all features
  • converters/test-data/x-graphql/expected/ - Expected GraphQL outputs

Get Help

Tips and Best Practices

1. Use Descriptive Type Names

{
  "x-graphql-type-name": "UserProfile" // ✅ Clear and specific
}
{
  "x-graphql-type-name": "Users" // ⚠️ Avoid plurals
}

2. Leverage Validation

Always validate your schemas before deployment:

jxql validate json-schema schema.json

3. Test Round-Trip Conversions

Ensure your schema survives round-trip conversion:

const original = readJsonSchema("schema.json");
const graphql = converter.convert(original, "json-to-graphql");
const backToJson = converter.convert(graphql, "graphql-to-json");
// Verify: original ≈ backToJson

4. Use Strict Mode for Critical Schemas

const converter = new Converter({
  validate: true,
  strict: true,
});

5. Follow GraphQL Naming Conventions

  • Types: PascalCase (e.g., UserProfile)
  • Fields: camelCase (e.g., userId, firstName)
  • Enums: SCREAMING_SNAKE_CASE (e.g., USER_ROLE)

Quick Reference Card

JSON Schema TypeGraphQL TypeNon-Null
"type": "string"StringAdd x-graphql-field-non-null: true
"type": "integer"Intor use required array
"type": "number"Float
"type": "boolean"Boolean
"type": "array"[Type]Use x-graphql-field-type
"type": "object"Custom TypeDefine with x-graphql-type-name
X-GraphQL ExtensionPurpose
x-graphql-type-nameSet GraphQL type name
x-graphql-type-kindOBJECT, INTERFACE, UNION, INPUT_OBJECT, ENUM
x-graphql-field-nameOverride field name
x-graphql-field-typeExplicit GraphQL type
x-graphql-field-non-nullMake field required
x-graphql-implementsImplement interfaces
x-graphql-union-typesUnion member types
x-graphql-federation-keysFederation @key fields
x-graphql-federation-shareableMark as @shareable
x-graphql-skipExclude from GraphQL

Ready to start? Pick a use case above and try it out! For more details, see the complete documentation.

x-graphql ExtensionsAttribute Reference