{
  "$id": "https://json.schemastore.org/mockd.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "mockd configuration",
  "description": "Configuration file for mockd, a multi-protocol API mock server supporting HTTP, GraphQL, gRPC, WebSocket, MQTT, SSE, SOAP, and OAuth",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "version": {
      "type": "string",
      "description": "Configuration file version"
    },
    "name": {
      "type": "string",
      "description": "Name of this mock collection"
    },
    "mocks": {
      "type": "array",
      "description": "List of mock endpoint definitions",
      "items": {
        "$ref": "#/definitions/mock"
      }
    },
    "statefulResources": {
      "type": "array",
      "description": "Deprecated: Prefer tables + extend pattern. Legacy stateful CRUD resources that persist data across requests.",
      "deprecated": true,
      "items": {
        "$ref": "#/definitions/statefulResource"
      }
    },
    "customOperations": {
      "type": "array",
      "description": "Multi-step operations on stateful resources",
      "items": {
        "$ref": "#/definitions/customOperation"
      }
    },
    "imports": {
      "type": "array",
      "description": "Import API specs (OpenAPI, Swagger, WSDL, etc.) and namespace their mocks",
      "items": {
        "$ref": "#/definitions/importEntry"
      }
    },
    "tables": {
      "type": "array",
      "description": "Stateful data tables. Tables are pure data stores with no routing — endpoints are bound via extend.",
      "items": {
        "$ref": "#/definitions/tableConfig"
      }
    },
    "extend": {
      "type": "array",
      "description": "Bind imported mocks to stateful tables with explicit actions",
      "items": {
        "$ref": "#/definitions/extendBinding"
      }
    },
    "workspaces": {
      "type": "array",
      "description": "Logical groupings of mocks. Each workspace provides isolated mock environments within a single mockd instance.",
      "items": {
        "$ref": "#/definitions/workspaceConfig"
      }
    },
    "serverConfig": {
      "$ref": "#/definitions/serverConfig"
    }
  },
  "definitions": {
    "workspaceConfig": {
      "type": "object",
      "description": "A workspace defines a logical grouping of mocks.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Unique name for this workspace (required)"
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of this workspace"
        },
        "engines": {
          "type": "array",
          "description": "Engine names this workspace is assigned to",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "mock": {
      "type": "object",
      "description": "A mock endpoint definition. The 'type' field determines which protocol spec to use.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this mock. Auto-generated if omitted."
        },
        "type": {
          "type": "string",
          "description": "Protocol type for this mock",
          "enum": ["http", "websocket", "graphql", "grpc", "soap", "mqtt", "oauth"]
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for this mock"
        },
        "description": {
          "type": "string",
          "description": "Description of what this mock does"
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this mock is active (default: true)",
          "default": true
        },
        "folderId": {
          "type": "string",
          "description": "Folder this mock belongs to"
        },
        "workspaceId": {
          "type": "string",
          "description": "Workspace this mock belongs to"
        },
        "http": {
          "$ref": "#/definitions/httpSpec"
        },
        "websocket": {
          "$ref": "#/definitions/websocketSpec"
        },
        "graphql": {
          "$ref": "#/definitions/graphqlSpec"
        },
        "grpc": {
          "$ref": "#/definitions/grpcSpec"
        },
        "soap": {
          "$ref": "#/definitions/soapSpec"
        },
        "mqtt": {
          "$ref": "#/definitions/mqttSpec"
        },
        "oauth": {
          "$ref": "#/definitions/oauthSpec"
        }
      },
      "additionalProperties": true
    },

    "httpSpec": {
      "type": "object",
      "description": "HTTP mock specification",
      "properties": {
        "priority": {
          "type": "integer",
          "description": "Match priority (higher wins when multiple mocks match)",
          "default": 0
        },
        "matcher": {
          "$ref": "#/definitions/httpMatcher"
        },
        "response": {
          "$ref": "#/definitions/httpResponse"
        },
        "sse": {
          "type": "object",
          "description": "Server-Sent Events configuration (mutually exclusive with response)",
          "additionalProperties": true,
          "properties": {
            "events": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "type": { "type": "string", "description": "Event type" },
                  "data": { "description": "Event data (string or object)" },
                  "id": { "type": "string" },
                  "delay": { "type": "integer", "description": "Delay in ms before this event" }
                }
              }
            }
          }
        },
        "chunked": {
          "type": "object",
          "description": "Chunked transfer encoding configuration",
          "additionalProperties": true,
          "properties": {
            "chunkSize": { "type": "integer" },
            "chunkDelay": { "type": "integer", "description": "Delay between chunks in ms" },
            "data": { "type": "string" },
            "dataFile": { "type": "string" }
          }
        },
        "validation": {
          "$ref": "#/definitions/requestValidation"
        },
        "statefulOperation": {
          "type": "string",
          "description": "Name of a custom operation to execute instead of a static response"
        }
      },
      "additionalProperties": true
    },

    "httpMatcher": {
      "type": "object",
      "description": "Request matching rules",
      "properties": {
        "method": {
          "type": "string",
          "description": "HTTP method to match",
          "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
        },
        "path": {
          "type": "string",
          "description": "URL path to match. Supports {param} patterns (e.g., /api/users/{id})"
        },
        "pathPattern": {
          "type": "string",
          "description": "Regex pattern for path matching (mutually exclusive with path)"
        },
        "headers": {
          "type": "object",
          "description": "Headers to match (glob patterns with * supported)",
          "additionalProperties": { "type": "string" }
        },
        "queryParams": {
          "type": "object",
          "description": "Query parameters to match (exact match)",
          "additionalProperties": { "type": "string" }
        },
        "bodyContains": {
          "type": "string",
          "description": "Match requests containing this substring in the body"
        },
        "bodyEquals": {
          "type": "string",
          "description": "Match requests with this exact body"
        },
        "bodyPattern": {
          "type": "string",
          "description": "Regex pattern to match against the request body"
        },
        "bodyJsonPath": {
          "type": "object",
          "description": "JSONPath expressions to match against the request body",
          "additionalProperties": true
        },
        "mtls": {
          "type": "object",
          "description": "mTLS client certificate matching",
          "additionalProperties": true,
          "properties": {
            "requireAuth": { "type": "boolean" },
            "cn": { "type": "string", "description": "Common Name to match" },
            "cnPattern": { "type": "string", "description": "Regex pattern for CN" },
            "ou": { "type": "string" },
            "o": { "type": "string" },
            "fingerprint": { "type": "string" }
          }
        }
      },
      "additionalProperties": true
    },

    "httpResponse": {
      "type": "object",
      "description": "Response configuration. Supports template expressions like {{uuid}}, {{faker.name}}, {{request.Path}}",
      "properties": {
        "statusCode": {
          "type": "integer",
          "description": "HTTP status code",
          "minimum": 100,
          "maximum": 599,
          "default": 200
        },
        "headers": {
          "type": "object",
          "description": "Response headers",
          "additionalProperties": { "type": "string" }
        },
        "body": {
          "description": "Response body (string or JSON object). Supports template expressions: {{uuid}}, {{faker.name}}, {{faker.email}}, {{now}}, {{random.Int 1 100}}, {{request.Method}}, etc."
        },
        "bodyFile": {
          "type": "string",
          "description": "Path to a file to use as the response body (relative to config file)"
        },
        "delayMs": {
          "type": "integer",
          "description": "Response delay in milliseconds",
          "minimum": 0,
          "default": 0
        }
      },
      "additionalProperties": true
    },

    "websocketSpec": {
      "type": "object",
      "description": "WebSocket mock specification",
      "required": ["path"],
      "properties": {
        "path": { "type": "string", "description": "WebSocket endpoint path" },
        "subprotocols": { "type": "array", "items": { "type": "string" } },
        "echoMode": { "type": "boolean", "description": "Echo received messages back" },
        "maxMessageSize": { "type": "integer" },
        "maxConnections": { "type": "integer" },
        "idleTimeout": { "type": "string", "description": "Duration string (e.g., '30s')" },
        "matchers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "match": {
                "type": "object",
                "properties": {
                  "type": { "type": "string", "enum": ["exact", "contains", "regex", "jsonpath"] },
                  "value": { "type": "string" }
                }
              },
              "response": {
                "type": "object",
                "properties": {
                  "type": { "type": "string", "enum": ["text", "json", "binary"] },
                  "value": { "description": "Response value" },
                  "delay": { "type": "string" }
                }
              }
            }
          }
        },
        "heartbeat": {
          "type": "object",
          "properties": {
            "enabled": { "type": "boolean" },
            "interval": { "type": "string" }
          }
        }
      },
      "additionalProperties": true
    },

    "graphqlSpec": {
      "type": "object",
      "description": "GraphQL mock specification",
      "required": ["path"],
      "properties": {
        "path": { "type": "string", "description": "GraphQL endpoint path" },
        "schema": { "type": "string", "description": "Inline GraphQL SDL schema" },
        "schemaFile": { "type": "string", "description": "Path to GraphQL schema file" },
        "introspection": { "type": "boolean", "description": "Enable introspection queries" },
        "resolvers": {
          "type": "object",
          "description": "Map of operation names to resolver configs",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "response": { "description": "Response data (string or object)" },
              "delay": { "type": "string" },
              "error": {
                "type": "object",
                "properties": {
                  "message": { "type": "string" },
                  "path": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "subscriptions": {
          "type": "object",
          "description": "Map of subscription names to configs",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "events": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "data": { "description": "Event data" },
                    "delay": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "additionalProperties": true
    },

    "grpcSpec": {
      "type": "object",
      "description": "gRPC mock specification",
      "properties": {
        "port": { "type": "integer", "description": "gRPC server port" },
        "protoFile": { "type": "string", "description": "Path to .proto file" },
        "protoFiles": { "type": "array", "items": { "type": "string" } },
        "importPaths": { "type": "array", "items": { "type": "string" } },
        "reflection": { "type": "boolean", "description": "Enable gRPC reflection" },
        "services": {
          "type": "object",
          "description": "Map of service names to configs",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "methods": {
                "type": "object",
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "response": { "description": "Response data" },
                    "responses": { "type": "array", "description": "Streaming responses" },
                    "delay": { "type": "string" },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": { "type": "string", "description": "gRPC status code (e.g., NOT_FOUND)" },
                        "message": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "additionalProperties": true
    },

    "soapSpec": {
      "type": "object",
      "description": "SOAP mock specification",
      "required": ["path"],
      "properties": {
        "path": { "type": "string", "description": "SOAP endpoint path" },
        "wsdlFile": { "type": "string", "description": "Path to WSDL file" },
        "wsdl": { "type": "string", "description": "Inline WSDL content" },
        "operations": {
          "type": "object",
          "description": "Map of operation names to configs",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "soapAction": { "type": "string" },
              "response": { "type": "string", "description": "XML response body" },
              "delay": { "type": "string" },
              "statefulBinding": {
                "type": "object",
                "description": "Bind this operation to a stateful table+action",
                "properties": {
                  "table": { "type": "string", "description": "Stateful table name (e.g., users)" },
                  "action": { "type": "string", "enum": ["get", "list", "create", "update", "patch", "delete", "custom"] },
                  "operation": { "type": "string", "description": "Custom operation name (required when action is custom)" }
                },
                "required": ["table", "action"]
              },
              "fault": {
                "type": "object",
                "properties": {
                  "code": { "type": "string" },
                  "message": { "type": "string" },
                  "detail": { "type": "string" }
                }
              }
            }
          }
        }
      },
      "additionalProperties": true
    },

    "mqttSpec": {
      "type": "object",
      "description": "MQTT mock broker specification",
      "properties": {
        "port": { "type": "integer", "description": "MQTT broker port" },
        "tls": {
          "type": "object",
          "properties": {
            "enabled": { "type": "boolean" },
            "certFile": { "type": "string" },
            "keyFile": { "type": "string" }
          }
        },
        "auth": {
          "type": "object",
          "properties": {
            "enabled": { "type": "boolean" },
            "users": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "username": { "type": "string" },
                  "password": { "type": "string" },
                  "acl": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "topic": { "type": "string" },
                        "access": { "type": "string", "enum": ["read", "write", "readwrite"] }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "topics": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["topic"],
            "properties": {
              "topic": { "type": "string", "description": "MQTT topic pattern" },
              "qos": { "type": "integer", "minimum": 0, "maximum": 2 },
              "retain": { "type": "boolean" },
              "messages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "payload": { "type": "string" },
                    "delay": { "type": "string" },
                    "repeat": { "type": "boolean" },
                    "interval": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "additionalProperties": true
    },

    "oauthSpec": {
      "type": "object",
      "description": "OAuth 2.0 / OIDC mock provider specification",
      "required": ["issuer"],
      "properties": {
        "issuer": { "type": "string", "description": "OAuth issuer URL" },
        "tokenExpiry": { "type": "string", "description": "Token expiry duration (e.g., '1h')" },
        "refreshExpiry": { "type": "string" },
        "defaultScopes": { "type": "array", "items": { "type": "string" } },
        "clients": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["clientId", "clientSecret"],
            "properties": {
              "clientId": { "type": "string" },
              "clientSecret": { "type": "string" },
              "redirectUris": { "type": "array", "items": { "type": "string" } },
              "grantTypes": { "type": "array", "items": { "type": "string" } }
            }
          }
        },
        "users": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["username", "password"],
            "properties": {
              "username": { "type": "string" },
              "password": { "type": "string" },
              "claims": { "type": "object", "additionalProperties": true }
            }
          }
        }
      },
      "additionalProperties": true
    },

    "statefulResource": {
      "type": "object",
      "description": "A stateful CRUD resource that persists data across requests",
      "required": ["name"],
      "properties": {
        "name": { "type": "string", "description": "Resource name (used in URLs)" },
        "idField": { "type": "string", "description": "Field to use as item ID", "default": "id" },
        "idStrategy": { "type": "string", "description": "ID generation strategy", "enum": ["uuid", "prefix", "ulid", "sequence", "short"] },
        "idPrefix": { "type": "string", "description": "ID prefix when idStrategy is 'prefix' (e.g., 'cus_')" },
        "parentField": { "type": "string", "description": "Foreign key field for nested resources (e.g., filter sub-resources by parent ID)" },
        "maxItems": { "type": "integer", "description": "Maximum items in the collection" },
        "seedData": {
          "type": "array",
          "description": "Initial data to populate the resource",
          "items": { "type": "object", "additionalProperties": true }
        },
        "validation": {
          "type": "object",
          "description": "Validation rules for create/update operations",
          "additionalProperties": true,
          "properties": {
            "auto": { "type": "boolean", "description": "Auto-infer validation from seed data" },
            "required": { "type": "array", "items": { "type": "string" } },
            "fields": {
              "type": "object",
              "additionalProperties": { "$ref": "#/definitions/fieldValidator" }
            }
          }
        },
        "response": {
          "$ref": "#/definitions/responseTransform",
          "description": "Default response transform for all bindings to this resource"
        },
        "relationships": {
          "type": "object",
          "description": "Maps field names to related tables for ?expand[] support",
          "additionalProperties": {
            "$ref": "#/definitions/relationship"
          }
        }
      },
      "additionalProperties": true
    },

    "customOperation": {
      "type": "object",
      "description": "A multi-step operation on stateful resources (e.g., TransferFunds)",
      "required": ["name", "steps"],
      "properties": {
        "name": { "type": "string", "description": "Operation name" },
        "consistency": { "type": "string", "enum": ["best_effort", "atomic"], "default": "best_effort" },
        "steps": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["type"],
            "properties": {
              "type": { "type": "string", "enum": ["read", "update", "delete", "create", "set", "list", "validate"] },
              "resource": { "type": "string" },
              "id": { "type": "string", "description": "Item ID (supports expressions)" },
              "as": { "type": "string", "description": "Variable name to store result" },
              "set": { "type": "object", "additionalProperties": { "type": "string" } },
              "var": { "type": "string" },
              "value": { "type": "string" },
              "filter": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field filters for list steps (values can be expr expressions)" },
              "condition": { "type": "string", "description": "Boolean expr expression for validate steps — halts operation if false" },
              "errorMessage": { "type": "string", "description": "Error message returned when a validate step's condition is false" },
              "errorStatus": { "type": "integer", "description": "HTTP status code returned when a validate step fails (default: 400)" }
            }
          }
        },
        "response": {
          "type": "object",
          "description": "Expression map for the response",
          "additionalProperties": { "type": "string" }
        }
      },
      "additionalProperties": true
    },

    "serverConfig": {
      "type": "object",
      "description": "Server-level configuration for ports, TLS, CORS, rate limiting, etc.",
      "properties": {
        "httpPort": { "type": "integer", "default": 4280 },
        "httpsPort": { "type": "integer", "default": 0 },
        "adminPort": { "type": "integer", "default": 4290 },
        "logRequests": { "type": "boolean" },
        "maxLogEntries": { "type": "integer" },
        "readTimeout": { "type": "integer", "description": "Read timeout in seconds" },
        "writeTimeout": { "type": "integer", "description": "Write timeout in seconds" },
        "maxConnections": { "type": "integer" },
        "tls": {
          "type": "object",
          "properties": {
            "enabled": { "type": "boolean" },
            "certFile": { "type": "string" },
            "keyFile": { "type": "string" },
            "autoGenerateCert": { "type": "boolean" }
          }
        },
        "cors": {
          "type": "object",
          "properties": {
            "enabled": { "type": "boolean" },
            "allowOrigins": { "type": "array", "items": { "type": "string" } },
            "allowMethods": { "type": "array", "items": { "type": "string" } },
            "allowHeaders": { "type": "array", "items": { "type": "string" } },
            "allowCredentials": { "type": "boolean" },
            "maxAge": { "type": "integer" }
          }
        },
        "rateLimit": {
          "type": "object",
          "properties": {
            "enabled": { "type": "boolean" },
            "requestsPerSecond": { "type": "number" },
            "burstSize": { "type": "integer" }
          }
        },
        "chaos": {
          "$ref": "#/definitions/chaosConfig"
        }
      },
      "additionalProperties": true
    },

    "chaosConfig": {
      "type": "object",
      "description": "Chaos fault injection configuration",
      "properties": {
        "enabled": { "type": "boolean" },
        "global": {
          "type": "object",
          "properties": {
            "latency": {
              "type": "object",
              "properties": {
                "min": { "type": "string" },
                "max": { "type": "string" },
                "probability": { "type": "number", "minimum": 0, "maximum": 1 }
              }
            },
            "errorRate": {
              "type": "object",
              "properties": {
                "probability": { "type": "number", "minimum": 0, "maximum": 1 },
                "statusCodes": { "type": "array", "items": { "type": "integer" } }
              }
            },
            "bandwidth": {
              "type": "object",
              "properties": {
                "bytesPerSecond": { "type": "integer" },
                "probability": { "type": "number", "minimum": 0, "maximum": 1 }
              }
            }
          }
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "pathPattern": { "type": "string" },
              "methods": { "type": "array", "items": { "type": "string" } },
              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
              "faults": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string", "enum": ["latency", "error", "timeout", "corrupt_body", "empty_response", "slow_body", "connection_reset", "partial_response", "circuit_breaker", "retry_after", "progressive_degradation", "chunked_dribble"] },
                    "probability": { "type": "number", "minimum": 0, "maximum": 1 },
                    "config": { "type": "object", "additionalProperties": true }
                  }
                }
              }
            }
          }
        }
      },
      "additionalProperties": true
    },

    "requestValidation": {
      "type": "object",
      "description": "Request validation rules",
      "properties": {
        "required": { "type": "array", "items": { "type": "string" } },
        "fields": {
          "type": "object",
          "additionalProperties": { "$ref": "#/definitions/fieldValidator" }
        },
        "mode": { "type": "string", "enum": ["strict", "warn", "permissive"] },
        "failStatus": { "type": "integer" }
      },
      "additionalProperties": true
    },

    "fieldValidator": {
      "type": "object",
      "description": "Field validation rules",
      "properties": {
        "type": { "type": "string", "enum": ["string", "number", "integer", "boolean", "array", "object"] },
        "required": { "type": "boolean" },
        "nullable": { "type": "boolean" },
        "minLength": { "type": "integer" },
        "maxLength": { "type": "integer" },
        "pattern": { "type": "string" },
        "format": { "type": "string", "enum": ["email", "uuid", "date", "datetime", "uri", "ipv4", "ipv6", "hostname"] },
        "min": { "type": "number" },
        "max": { "type": "number" },
        "minItems": { "type": "integer" },
        "maxItems": { "type": "integer" },
        "uniqueItems": { "type": "boolean" },
        "enum": { "type": "array" },
        "message": { "type": "string", "description": "Custom error message" }
      },
      "additionalProperties": true
    },

    "importEntry": {
      "type": "object",
      "description": "An API spec import with optional namespace",
      "required": ["path"],
      "properties": {
        "path": { "type": "string", "description": "File path to the API spec (relative to config file)" },
        "url": { "type": "string", "description": "URL to fetch the API spec from (alternative to path)" },
        "as": { "type": "string", "description": "Namespace prefix for imported mocks (e.g., 'stripe')" },
        "format": { "type": "string", "description": "Explicit format (auto-detected if omitted)", "enum": ["openapi", "swagger", "postman", "har", "wiremock", "wsdl", "mockoon", "curl", "yaml", "json"] }
      },
      "additionalProperties": false
    },

    "tableConfig": {
      "type": "object",
      "description": "A stateful data table definition",
      "required": ["name"],
      "properties": {
        "name": { "type": "string", "description": "Table name (e.g., 'customers')" },
        "idField": { "type": "string", "description": "Field to use as item ID", "default": "id" },
        "idStrategy": { "type": "string", "description": "ID generation strategy", "enum": ["uuid", "prefix", "ulid", "sequence", "short"] },
        "idPrefix": { "type": "string", "description": "ID prefix when idStrategy is 'prefix' (e.g., 'cus_')" },
        "maxItems": { "type": "integer", "description": "Maximum items in the collection" },
        "parentField": { "type": "string", "description": "Foreign key field for nested resources" },
        "seedData": {
          "type": "array",
          "description": "Initial data to populate the table",
          "items": { "type": "object", "additionalProperties": true }
        },
        "validation": {
          "type": "object",
          "description": "Validation rules for create/update operations",
          "additionalProperties": true
        },
        "response": {
          "$ref": "#/definitions/responseTransform",
          "description": "Default response transform for all bindings to this table"
        },
        "relationships": {
          "type": "object",
          "description": "Maps field names to related tables for ?expand[] support",
          "additionalProperties": {
            "$ref": "#/definitions/relationship"
          }
        }
      },
      "additionalProperties": true
    },

    "relationship": {
      "type": "object",
      "description": "Foreign key relationship to another table for ?expand[] support",
      "required": ["table"],
      "properties": {
        "table": {
          "type": "string",
          "description": "Target table name"
        },
        "field": {
          "type": "string",
          "description": "Field in target table to match (defaults to target's idField)"
        }
      },
      "additionalProperties": false
    },

    "extendBinding": {
      "type": "object",
      "description": "Binds an imported mock to a table with a specific action",
      "required": ["mock", "table", "action"],
      "properties": {
        "mock": { "type": "string", "description": "Mock reference: namespaced operationId (e.g., 'stripe.PostCustomers') or 'METHOD /path'" },
        "table": { "type": "string", "description": "Target table name" },
        "action": { "type": "string", "description": "Action to perform", "enum": ["create", "get", "list", "update", "patch", "delete", "custom"] },
        "operation": { "type": "string", "description": "Custom operation name (required when action is 'custom')" },
        "response": {
          "$ref": "#/definitions/responseTransform",
          "description": "Response transform override for this specific binding"
        }
      },
      "additionalProperties": false
    },

    "responseTransform": {
      "type": "object",
      "description": "Response transform configuration for shaping stateful resource responses",
      "properties": {
        "timestamps": {
          "type": "object",
          "properties": {
            "format": { "type": "string", "enum": ["unix", "iso8601", "rfc3339", "none"], "description": "Timestamp format" },
            "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field rename map (e.g., createdAt → created)" }
          }
        },
        "fields": {
          "type": "object",
          "properties": {
            "inject": { "type": "object", "additionalProperties": true, "description": "Fields to inject into every item" },
            "hide": { "type": "array", "items": { "type": "string" }, "description": "Fields to hide from responses" },
            "rename": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Rename field keys in responses (key is original name, value is output name)" },
            "wrapAsList": {
              "type": "object",
              "description": "Wraps specified array fields in list object envelopes ({object: 'list', data: [...], has_more: false}). Key is field name, value is envelope config.",
              "additionalProperties": {
                "$ref": "#/definitions/listWrapConfig"
              }
            }
          }
        },
        "list": {
          "type": "object",
          "properties": {
            "dataField": { "type": "string", "description": "Name of the array field (default: 'data')" },
            "extraFields": { "type": "object", "additionalProperties": true, "description": "Extra fields on list response" },
            "hideMeta": { "type": "boolean", "description": "Hide the default meta object" }
          }
        },
        "create": {
          "type": "object",
          "properties": {
            "status": { "type": "integer", "description": "HTTP status for create (default: 201)" }
          }
        },
        "delete": {
          "type": "object",
          "properties": {
            "status": { "type": "integer", "description": "HTTP status for delete (default: 204)" },
            "body": { "type": "object", "additionalProperties": true, "description": "Custom delete response body (supports {{item.field}} templates)" },
            "preserve": { "type": "boolean", "description": "When true, the item is not removed from the store. DELETE returns the configured response but the data is preserved. Useful for soft-delete APIs." }
          }
        },
        "errors": {
          "type": "object",
          "properties": {
            "wrap": { "type": "string", "description": "Wrap error in a named object (e.g., 'error')" },
            "fields": { "type": "object", "additionalProperties": { "type": "string" } },
            "typeMap": { "type": "object", "additionalProperties": { "type": "string" } },
            "codeMap": { "type": "object", "additionalProperties": { "type": "string" } }
          }
        }
      },
      "additionalProperties": true
    },

    "listWrapConfig": {
      "type": ["object", "null"],
      "description": "Configuration for wrapping an array field in a list object envelope. Null means default envelope with no URL.",
      "properties": {
        "url": {
          "type": "string",
          "description": "URL template for the sub-resource list. Supports {{fieldName}} substitution from the parent item."
        }
      },
      "additionalProperties": false
    }
  }
}