GraphQL Schema Export

FakeDataDSL can export schemas to GraphQL SDL (Schema Definition Language), making it easy to generate type-safe GraphQL APIs from your data schemas.

Quick Start

Ruby API

require 'fake_data_dsl'

# Load schema
schema = FakeDataDSL.load("schemas/user.dsl")

# Export to GraphQL
graphql = FakeDataDSL.to_graphql(schema)
puts graphql

CLI

# Export single schema
fake_data_dsl export User -d schemas -f graphql -o schema.graphql

# Export all schemas
fake_data_dsl export --all -d schemas -f graphql -o schema.graphql

Output Example

Given this DSL:

User:
  id: uuid
  name: text
  email: email
  age: number
  active: boolean
  role: enum(user, admin, moderator)

Generates this GraphQL:

# FakeDataDSL Generated GraphQL Schema
# Generated at: 2024-01-15T10:30:00Z

enum UserRoleEnum {
  USER
  ADMIN
  MODERATOR
}

type User {
  id: ID!
  name: String!
  email: String!
  age: Int!
  active: Boolean!
  role: UserRoleEnum!
}

type Query {
  user(id: ID!): User
  users(limit: Int = 10, offset: Int = 0): [User!]!
}

Type Mapping

FakeDataDSL types are mapped to GraphQL types:

FakeDataDSL GraphQL Notes
uuid, ulid, id_sequence ID Identifier types
text, name, email, phone String String types
number, integer, age Int Integer types
float, money, latitude Float Floating point
boolean Boolean Boolean type
date, timestamp String Dates as ISO strings
enum(...) enum Auto-generated enums
array(T) [T!]! Non-nullable arrays
Schema reference Schema Nested types

Features

Nullable Fields

Optional and nullable fields omit the !:

User:
  id: uuid
  bio?: text       # Optional field
  nickname: text?  # Nullable field

type User {
  id: ID!
  bio: String      # No ! (optional)
  nickname: String # No ! (nullable)
}

Enum Generation

Enums are automatically extracted and named:

Product:
  status: enum(draft, published, archived)
  category: enum(electronics, clothing, home)

enum ProductStatusEnum {
  DRAFT
  PUBLISHED
  ARCHIVED
}

enum ProductCategoryEnum {
  ELECTRONICS
  CLOTHING
  HOME
}

type Product {
  status: ProductStatusEnum!
  category: ProductCategoryEnum!
}

Array Fields

Arrays map to GraphQL list types:

Order:
  items: array(OrderItem, 1..10)
  tags: array(text, 0..5)

type Order {
  items: [OrderItem!]!
  tags: [String!]!
}

Schema References

Cross-schema references maintain their types:

Order:
  id: uuid
  customer: Customer
  items: array(OrderItem, 1..5)

type Order {
  id: ID!
  customer: Customer!
  items: [OrderItem!]!
}

Export All Schemas

Export an entire registry to a single GraphQL file:

registry = FakeDataDSL::Registry.new
registry.load_dir("schemas/")

graphql = FakeDataDSL.to_graphql_all(registry)
File.write("schema.graphql", graphql)

This generates:

  • All types from all schemas
  • All enums extracted from schemas
  • A Query type with CRUD-like queries for each type

Query Type Generation

When exporting all schemas, a Query type is automatically generated:

type Query {
  user(id: ID!): User
  users(limit: Int = 10, offset: Int = 0): [User!]!

  order(id: ID!): Order
  orders(limit: Int = 10, offset: Int = 0): [Order!]!

  product(id: ID!): Product
  products(limit: Int = 10, offset: Int = 0): [Product!]!
}

Customization

With Registry

Pass a registry for cross-schema reference resolution:

registry = FakeDataDSL::Registry.new
registry.load_dir("schemas/")

schema = registry.schema("User")
graphql = FakeDataDSL.to_graphql(schema, registry: registry)

Integration with GraphQL Servers

Ruby (graphql-ruby)

# Use the generated schema as a starting point
schema_string = FakeDataDSL.to_graphql_all(registry)
File.write("app/graphql/schema.graphql", schema_string)

# Then implement resolvers
class QueryType < GraphQL::Schema::Object
  field :user, UserType, null: true do
    argument :id, ID, required: true
  end

  def user(id:)
    User.find(id)
  end
end

Node.js

// Save the generated schema
const fs = require('fs');
const schema = fs.readFileSync('schema.graphql', 'utf8');

// Use with Apollo Server
const { ApolloServer } = require('apollo-server');
const typeDefs = gql(schema);

Best Practices

1. Keep Schemas in Sync

Generate GraphQL schemas as part of your build process:

# In CI or pre-commit hook
fake_data_dsl export --all -d schemas -f graphql -o schema.graphql
git diff --exit-code schema.graphql || echo "GraphQL schema out of sync!"

2. Use Consistent Naming

FakeDataDSL uses PascalCase for types and camelCase for fields:

UserProfile:          # → type UserProfile
  firstName: name     # → firstName: String!
  lastName: name      # → lastName: String!

3. Document Deprecated Fields

User:
  @deprecated "Use email_verified instead"
  verified: boolean
  email_verified: boolean

type User {
  verified: Boolean! @deprecated
  emailVerified: Boolean!
}

Limitations

  • Custom scalars not yet supported
  • Directives limited to @deprecated
  • Interfaces and unions not supported
  • Input types not generated (only output types)

See Also