Docs

MockQL Schema Documentation

Learn how to configure GraphQL schemas in MockQL to create realistic mock APIs for testing your applications.

MockQL helps developers create GraphQL mock APIs that generate realistic test data matching your API structure without modifying backend code.

Schema Construction

MockQL uses a top-down approach for schema creation. Start with the main Query type and define each type it uses, building your API structure like a tree.

Basic Schema Structure

type Query {
  listAllCategories: categoryConnection
}

type categoryConnection {
  categories: [category]
}

type category {
  sample_value: String @mock(type:"commerce.productDescription")
}

This creates a query that returns a connection containing a list of categories, each with a mocked product description.

Nested Type Structure

type Query {
  listAllCategories: categoryConnection
}

type categoryConnection {
  categories: [category]
}

type category {
  level1: level2
}

type level2 {
  level3: level4
}

type level4 {
  value: String @mock(type: "commerce.productDescription")
}

Creates a nested structure where each level references the next, allowing deep data hierarchies.

Adding and Extending Fields

Adding Fields to Existing Queries

type Query {
  listAllCategories: categoryConnection
}

type categoryConnection {
  sample_value: String @mock(type:"commerce.productDescription")  // New field
}
Important: When you modify a type in one query path, it does not affect other queries using the same type name. Each query path needs to be individually modified.

Creating New Custom Queries

type Query {
  customQuery: mycustomType  // Define a new custom type
}

type mycustomType {
  sample_url: [String] @mock(type:"image.url", count: 5)
  sample_value: String @mock(type:"commerce.productDescription")
}
Critical: For new queries, you must create entirely new custom types with mock directives. You cannot reuse existing backend types.

Overriding Existing Types

type Query {
  listAllCategories: categoryConnection
}

type categoryConnection {
  categories: [overrideCategory]  // Using a custom type
}

type overrideCategory {  // Create an entirely new type
  overrided_type_data: [String] @mock(type:"person.fullName", count: 2)
  nested_value: [mycustomType]
}

type mycustomType {
  sample_url: [String] @mock(type:"image.url", count: 5)
  sample_value: String @mock(type:"commerce.productDescription")
}

When overriding types, you must recreate all fields with mock directives as there's no merging between your mock types and backend data.

Mocking Data with Directives

Using the @mock Directive

// Basic usage - generates a fake product description
field: String @mock(type: "commerce.productDescription")

// Array with count parameter - generates 5 random image URLs
sample_url: [String] @mock(type: "image.url", count: 5)

// Using arrayElement to select from predefined values
status: String @mock(type: "helpers.arrayElement", values: ["ACTIVE", "INACTIVE"])

// Custom weighted choices
rarity: String @mock(type: "custom.weightedChoice", weightedValues: [["Common", 0.7], ["Rare", 0.2], ["Legendary", 0.1]])

// Number ranges with min/max
score: Int @mock(type: "number.int", min: 1, max: 100)

// Pattern-based generation
phone: String @mock(type: "helpers.regexpify", pattern: "\+1-[0-9]{3}-[0-9]{3}-[0-9]{4}")

// Nullable fields
description: String @mock(type: "lorem.paragraph", nullable: true, nullProbability: 0.3)

The @mock directive generates fake data based on the type and parameters you provide.

Mock Directive Parameters

Basic Parameters

  • type: Faker method to generate data (e.g., "internet.email")
  • count: Number of items for array fields
  • values: Array of possible values to pick from
  • value: Fixed value to always use

Number Parameters

  • min/max: Range for integer values
  • minFloat/maxFloat: Range for floating point values

Advanced Parameters

  • pattern: Regex pattern for string generation
  • nullable: Whether field can return null
  • nullProbability: Chance of returning null (0-1)
  • weightedValues: Array of [value, weight] pairs

Custom Types

  • custom.oneOf: Select one value from array
  • custom.randomSubset: Random subset from array
  • custom.weightedChoice: Weighted random selection
  • custom.incrementalId: Auto-incrementing ID

Popular Data Categories

Person

  • person.firstName
  • person.lastName
  • person.fullName
  • person.jobTitle
  • person.gender

Internet

  • internet.email
  • internet.userName
  • internet.url
  • internet.avatar
  • internet.domainName

Commerce

  • commerce.productName
  • commerce.price
  • commerce.productDescription
  • commerce.department

Date & Time

  • date.past
  • date.future
  • date.recent
  • date.month
  • date.weekday

Location

  • location.city
  • location.country
  • location.streetAddress
  • location.zipCode
  • location.latitude/longitude

Helpers

  • helpers.arrayElement
  • helpers.arrayElements
  • helpers.regexpify
  • helpers.randomize
  • helpers.slugify

MockQL supports all Faker.js categories including: string, number, internet, person, date, image, commerce, company, location, phone, system, lorem, finance, datatype, color, database, hacker, airline, animal, music, and word.

Example Queries

Complete Example with Response

Schema:

type Query {
  listAllCategories: categoryConnection
}

type categoryConnection {
  categories: [customCategory]
  nextToken: String @mock(type: "datatype.uuid")
  totalCount: Int @mock(type: "number.int", min: 10, max: 100)
}

type customCategory {
  category_id: String @mock(type: "string.uuid")
  category_name: String @mock(type: "commerce.productName")
  description: String @mock(type: "commerce.productDescription")
  status: String @mock(type: "helpers.arrayElement", 
    values: ["ACTIVE", "INACTIVE", "PENDING"])
  popularity_score: Float @mock(type: "number.float", 
    min: 0, max: 10)
}

Query:

query GetCategories {
  listAllCategories {
    categories {
      category_id
      category_name
      description
      status
      popularity_score
    }
    nextToken
    totalCount
  }
}

Response:

{
  "listAllCategories": {
    "categories": [
      {
        "category_id": "fae12d5b-3af7-4965-8c4f-21e58d3a6b4c",
        "category_name": "Handcrafted Metal Chair",
        "description": "Ergonomic design with premium materials",
        "status": "ACTIVE",
        "popularity_score": 8.7
      },
      {
        "category_id": "a9c53e8d-6b2f-47d1-9f8a-3c6e4b2d5a1f",
        "category_name": "Rustic Wooden Table",
        "description": "Natural wood grain with artisanal craftsmanship",
        "status": "PENDING", 
        "popularity_score": 6.2
      }
    ],
    "nextToken": "eyJsYXN0RXZhbHVhdGVkS2V5Ijp7ImlkIjoxMDB9fQ==",
    "totalCount": 42
  }
}

Key Limitations

No Backend Type Reuse

You cannot reuse backend types for custom queries. When defining a new query path, you must create entirely new types with mock directives.

// DON'T DO THIS - Won't work
type Query {
  myCustomQuery: ExistingBackendType  // WRONG
}

// INSTEAD DO THIS
type Query {
  myCustomQuery: MyCustomType  // Create new types
}

type MyCustomType {
  field1: String @mock(type: "commerce.productName")
}

No Enum Support

Use String with mock directives instead of enums:

type category {
  status: String @mock(type: "helpers.arrayElement", 
    values: ["ACTIVE", "INACTIVE"])
}

Editor Support

The editor provides code completion for mock directives. Press Alt+M to insert a mock directive template, or type @mock to trigger suggestions.

Pattern Usage Notes

Common Pattern Examples

// Phone number

\+1-[0-9]3-[0-9]3-[0-9]4

// Email pattern

[a-z]10\.[a-z]10@[a-z]10\.[a-z]5

// UUID v4

[0-9a-f]8-[0-9a-f]4-4[0-9a-f]3-[89ab][0-9a-f]3-[0-9a-f]12

Additional Limitations

  • No default values for fields
  • Multi-level arrays flatten to single arrays
  • Limited input parameter support
  • No merging between mock and backend data
  • Regular expressions need double escaping
  • Type names are case sensitive

Best Practices

●Top-Down Approach

Always define schemas from top (Query) to bottom (fields) for proper structure.

●Custom Types for New Queries

Create custom types for new queries rather than reusing existing types.

●Use Descriptive Naming

Clear, descriptive names improve readability and maintainability.

●Realistic Mock Data

Choose mock types that match expected real data for better testing.

●Use Editor Features

Take advantage of auto-completion and keyboard shortcuts (Alt+M) for faster schema creation.

●Test As You Go

Switch to the Explorer tab frequently to test your schema changes and ensure they work as expected.

Editor Shortcuts

Insert mock directiveAlt+M
Trigger suggestionsCtrl+Space
Save schemaCtrl+S
Auto-complete after typing@mock
Show parameter suggestionstype: "
View documentationHover over value