Core Concepts

Data Schemas & Contracts

Define the structure and validation rules for your API responses

What is a Schema?

A schema (or data contract) is a blueprint that defines the structure, data types, and validation rules for your API responses. It ensures consistency and predictability in your mock data.

Why Schemas Matter

  • ✓ Type Safety: Frontend knows what data types to expect
  • ✓ Consistency: All records follow the same structure
  • ✓ Validation: Catch errors before they reach production
  • ✓ Documentation: Self-documenting API contracts
  • ✓ Auto-generation: Smart mock data based on field types

Field Types

Mock API Builder supports various field types for realistic data:

String

Text data of any length

"name": "John Doe"

Use for: names, descriptions, addresses

Number

Integer or decimal values

"price": 29.99

Use for: prices, quantities, IDs

Boolean

True/false values

"isActive": true

Use for: flags, toggles, status

Email

Email address format

"email": "user@example.com"

Auto-validates email format

Date/DateTime

ISO 8601 date strings

"createdAt": "2024-01-15T10:30:00Z"

Use for: timestamps, birthdays

UUID

Unique identifier

"id": "550e8400-e29b-41d4-a716-..."

Use for: unique IDs

URL

Web address format

"website": "https://example.com"

Use for: links, avatar URLs

Array

List of items

"tags": ["javascript", "react"]

Use for: lists, collections

Object

Nested data structure

"address": { "city": "NYC" }

Use for: nested data

Enum

Limited set of values

"status": "active" | "pending"

Use for: status, role, category

Creating Schemas

You have three ways to define your data schema:

1. Manual Field Builder

Build your schema field-by-field using the visual interface:

Example: User Schema

Stringname
Emailemail
Numberage
BooleanisActive

Best for:

• Simple schemas
• Quick prototyping
• Learning and experimentation

2. JSON Schema Editor

Write your schema directly in JSON format:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Best for:

• Complex nested structures
• Copy/paste from existing APIs
• Developers comfortable with JSON

3. OpenAPI Import

Import complete schemas from OpenAPI/Swagger specifications:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

Best for:

• Existing API specs
• Team standardization
• Large-scale projects

Nested Objects & Arrays

Nested Objects

Create complex data structures with nested properties:

{
  "id": 1,
  "name": "John Doe",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "zipCode": "10001",
    "coordinates": {
      "lat": 40.7128,
      "lng": -74.0060
    }
  }
}

Arrays of Objects

Define arrays containing complex objects:

{
  "id": 1,
  "name": "John Doe",
  "orders": [
    {
      "orderId": "ORD-001",
      "total": 99.99,
      "status": "completed"
    },
    {
      "orderId": "ORD-002",
      "total": 149.99,
      "status": "pending"
    }
  ]
}

Field Constraints & Validation

Required Fields

Mark fields that must always have a value

required: ["id", "name", "email"]
String Length

Set minimum and maximum character limits

minLength: 3, maxLength: 50
Number Range

Define acceptable numeric ranges

minimum: 0, maximum: 100
Pattern Matching

Use regex for custom validation

pattern: "^[A-Z]{2}-[0-9]{4}$"

Best Practices

✓ Start Simple, Then Expand

Begin with basic fields, then add complexity as needed. Don't over-engineer from the start.

✓ Use Descriptive Field Names

✓ firstName, emailAddress

✗ fn, em

✓ Be Consistent with Naming

Choose a convention and stick to it:

  • • camelCase: firstName
  • • snake_case: first_name
  • • PascalCase: FirstName
✓ Include Metadata Fields

Always include: id,createdAt,updatedAt for better tracking

✓ Match Your Production API

Keep your mock schema identical to your real API to avoid integration issues later.

Common Patterns

User Resource
{
  "id": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "avatar": "https://...",
  "role": "user",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z"
}
Product Resource
{
  "id": 1,
  "name": "Product Name",
  "description": "Product description...",
  "price": 29.99,
  "currency": "USD",
  "stock": 100,
  "category": "electronics",
  "images": ["url1", "url2"],
  "tags": ["new", "featured"]
}
Paginated List Response
{
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 5,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}
Previous: Endpoints & ResourcesNext: Mock Data Generation