Concept	Syntax	Example
Scalar	`String`, `Int`, `Float`, `Boolean`, `ID`	`name: String!`
Object	`type Name { fields }`	`type User { id: ID! }`
Input	`input Name { fields }`	`input CreateUserInput { name: String! }`
Enum	`enum Name { VALUES }`	`enum Status { ACTIVE INACTIVE }`
List	`[Type]` or `[Type!]!`	`tags: [String!]!`
Non-null	`Type!`	`id: ID!`

Core Concepts

1. Type System

# Scalar types (built-in)
type Example {
  id: ID!           # Unique identifier
  name: String!     # Text
  age: Int          # Integer (nullable)
  score: Float!     # Decimal
  active: Boolean!  # True/false
}

# Custom scalars
scalar DateTime
scalar JSON
scalar Upload

# Object types
type User {
  id: ID!
  email: String!
  profile: Profile    # Nested object
  posts: [Post!]!     # List of objects
}

type Profile {
  bio: String
  avatar: String
}

# Enums
enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}

# Input types (for mutations)
input CreateUserInput {
  email: String!
  name: String!
  role: UserRole = VIEWER  # Default value
}

# Interfaces
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

# Unions
union SearchResult = User | Post | Comment

2. Queries

# Schema definition
type Query {
  # Single item
  user(id: ID!): User

  # List with optional filter
  users(filter: UserFilter, limit: Int = 10): [User!]!

  # Search
  search(query: String!): [SearchResult!]!
}

# Client query examples
query GetUser {
  user(id: "123") {
    id
    name
    email
  }
}

query GetUsersWithFilter {
  users(filter: { role: ADMIN }, limit: 5) {
    id
    name
  }
}

# With variables
query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
  }
}
# Variables: { "userId": "123" }

# With aliases
query GetTwoUsers {
  admin: user(id: "1") { name }
  editor: user(id: "2") { name }
}

# With fragments
fragment UserFields on User {
  id
  name
  email
}

query GetUsers {
  users {
    ...UserFields
  }
}

3. Mutations

# Schema definition
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): DeletePayload!
}

type CreateUserPayload {
  user: User
  errors: [Error!]!
}

# Client mutation
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      name
    }
    errors {
      field
      message
    }
  }
}
# Variables: { "input": { "email": "test@example.com", "name": "Test" } }

4. Subscriptions

# Schema definition
type Subscription {
  userCreated: User!
  messageReceived(channelId: ID!): Message!
}

# Client subscription
subscription OnUserCreated {
  userCreated {
    id
    name
    createdAt
  }
}

subscription OnMessage($channelId: ID!) {
  messageReceived(channelId: $channelId) {
    id
    content
    sender { name }
  }
}

Common Patterns

Nullability Cheat Sheet

type Example {
  # Required field - never null
  id: ID!

  # Optional field - can be null
  nickname: String

  # Required list, optional items
  tags: [String]!        # [], ["a", null, "b"]

  # Required list, required items (most common)
  categories: [Category!]!  # [], [cat1, cat2]

  # Optional list (avoid - ambiguous)
  # items: [Item]  # null vs [] unclear
}

Input Validation Pattern

input CreateUserInput {
  email: String!      # Required
  name: String!       # Required
  age: Int            # Optional
  role: UserRole = VIEWER  # Optional with default
}

Troubleshooting

Error	Cause	Solution
`Cannot query field "x"`	Field not in schema	Check spelling, verify schema
`Variable "$x" not defined`	Missing variable declaration	Add to query signature
`Expected non-null, got null`	Resolver returned null for `!` field	Fix resolver or make nullable
`Unknown type "X"`	Type not defined	Add type definition

Debug Commands

# Validate schema
npx graphql-inspector validate schema.graphql

# Introspect remote schema
npx graphql-inspector introspect http://localhost:4000/graphql

# Check for breaking changes
npx graphql-inspector diff old.graphql new.graphql

Usage

Skill("graphql-fundamentals")

Related Skills

graphql-schema-design - Advanced schema patterns
graphql-resolvers - Implementing resolvers
graphql-codegen - TypeScript type generation

Related Agent

01-graphql-fundamentals - For detailed guidance

graphql-fundamentals

GraphQL Fundamentals Skill

Overview

Quick Reference