Configuration

The config is a YAML file.

• Unknown keys are errors.
• Every problem is reported at once, with its key path (server.scaffold.port).
• Paths are relative to the config file.

config.schema.json describes every key. The first line of the example points editors at it.

The main keys, with example values:

# yaml-language-server: $schema=https://raw.githubusercontent.com/mockzilla/mockzilla-codegen/main/config.schema.json
spec:
  path: ./openapi.yaml
  overlays: [./overlays/go-names.yaml]
  filter:
    include:
      paths: [/pets]
      tags: [pets]
      operation-ids: [listPets]
      webhooks: [newPet]
      extensions: [x-public]
      schema-properties: {Pet: [name, tag]}
    exclude:
      tags: [internal]
  prune: true
  simplify:
    unions: true
    optional-properties: {min: 1, max: 3, seed: 1}
package: api
header: "Copyright 2026 Acme. Code generated by mockzilla-codegen. DO NOT EDIT."
naming:
  initialisms: [PSP]
  enum-prefix: true
imports:
  - package: github.com/google/uuid
  - {package: example.com/shop/tenant, alias: tn}
models:
  int-type: int64
  descriptions: false
  extra-tags: [yaml]
  validation: {response: true}
  error-mapping: {ErrorResponse: error.message}
  format-types: {uuid: {type: uuid.UUID}}
  nullable: true
server:
  framework: chi
  name: PetService
  validation: {request: true, response: false}
  multipart-max-memory: 64MB
  scaffold:
    service: ./api/service.go
    middleware: ./api/middleware.go
    main: ./cmd/server/main.go
    overwrite: false
    port: 9090
    timeout: 45s
client:
  name: PetClient
  timeout: 5s
  with-response: true
  streaming: true
mcp:
  default-skip: false
templates:
  server.service-header: {file: ./templates/header.tmpl}
  server.request-options-extra: Tenant tn.ID
user-context:
  owner: platform
output:
  file: ./api/gen.go
  files:
    ./api/server.gen.go: [server]
  packages: {./models: models}
  format: true

Blocks #

Block	What it does
spec	the input spec and how to prepare it (overlays, filter, prune, simplify)
models, server, client, mcp	what to generate
templates, user-context	overrides of the template blocks a config may replace, and the values they see as .User (blocks)
extra-files	files written from your own templates, on the service, the operations and the types (extra files)
imports	the packages that the text of a block or an x-go-type names. A generated file imports one when its code refers to it (imports).
output	where the files go. Only this block says where.

The spec file #

A spec file is JSON or YAML 1.2 and holds one document. So 1_000 is a string and 012 is the number 12.

What to generate #

Models are always on. The other blocks (server, client, mcp) are on when present, even as a bare key (mcp:). mcp needs client.

Output files #

output.file is the default file for every part. output.files moves parts to other files with selectors. The most specific selector wins. A selector can be listed only once.

Selector	Parts
models	every model part
models.<part>	types, enums, unions, params, bodies, responses
server	every server part
server.<part>	service, adapter, router, errors
client, client.<part>	core, options, operations, responses
mcp, mcp.<part>	tools, inputs

Packages #

• The folder of output.file uses package.
• Other folders use output.packages, else their own name.
• output.packages wins over package when both name the same folder.
• Output in more than one folder needs a module path for the imports between them. It comes from the nearest go.mod, or from output.module.
• Folders that import each other are an error.

What can be split #

The model parts refer to each other's types, so they share one folder. Split them into files, not packages.

client.operations sits with client.core, whose methods it declares.

Every other part can have a package of its own.

examples/layout generates one spec in five layouts:

• parts in several files of one package
• models apart from the rest
• each family in its own package
• the service interface apart from the router
• a client in a folder that output.packages names

Defaults #

Key	Default
package	folder name of output.file
header	Code generated by mockzilla-codegen. DO NOT EDIT.
output.file	./gen.go
output.format	true
spec.prune	true
naming.enum-prefix	true
models.int-type	int
models.descriptions	true
server.name	Service
server.multipart-max-memory	32MB
server.scaffold.port	8080
server.scaffold.timeout	30s
client.name	Client
client.timeout	3s