Deterministic Mode

Every request to Mimikos produces the same response, every time. Restart the server, replay the request — identical output. This is the default mode and the foundation of Mimikos’s design.

mimikos start petshop.yaml

Deterministic mode is the default. No flags needed.

Your spec already has mock data

OpenAPI has supported example values since version 3.0. Most specs already use them — or should. These examples live alongside the schemas they describe, authored and maintained by the people who design the API.

Yet most mock tools ignore them. They require separate config files, fixture directories, or mock definition DSLs — all of which duplicate information already in the spec and inevitably drift from it as the API evolves.

Mimikos takes the opposite approach: your spec is the only input. If you define example values in your spec, Mimikos uses them directly. No config files to create. No mock data to maintain in a separate location. No drift, because there’s nothing to drift from.

How examples work in your spec

Mimikos recognizes examples at three levels, from broadest to narrowest scope:

Media-type examples

A media-type example defines the entire response body. Mimikos returns it as-is — no field generation, no response validation.

responses:
  "200":
    content:
      application/json:
        example:
          id: 1
          name: "Buddy"
          status: "available"

The spec author wrote both the schema and the example, so Mimikos trusts it completely.

Object and array schema examples

An example on an object or array schema bypasses generation for that entire subtree. Mimikos returns the authored example instead of walking the schema’s properties or items.

properties:
  address:
    type: object
    properties:
      city:
        type: string
      zip:
        type: string
    example:
      city: "Portland"
      zip: "97201"
  tags:
    type: array
    items:
      type: string
    example:
      - "friendly"
      - "outdoor"

This works at any nesting depth. A child object with an example gets that example even when the parent object is generated normally — sibling fields are unaffected. This gives you fine-grained control: example the fields you care about, let Mimikos generate the rest.

Property-level examples

An example on a primitive property provides the value for that single field:

properties:
  status:
    type: string
    example: "active"
  priority:
    type: integer
    example: 3

If a property has an example, that value takes priority over semantic mapping and faker generation.

What happens without examples

Not every field needs an explicit example. Mimikos generates realistic values for the rest using a priority chain:

1. const — if the schema defines a constant, use it
2. enum — pick deterministically from the allowed values
3. example — use the spec author’s example value (as described above)
4. Semantic mapping — match the field name to a contextually appropriate faker (e.g., email → email address)
5. Faker fallback — generate a type-valid value using format-aware faker functions

Semantic field mapping

For fields without explicit examples, Mimikos recognizes 120+ field name patterns and generates contextually appropriate values:

Field name pattern	Generated value
email, emailAddress	alice.johnson@example.com
firstName, first_name	Lori
phone, phoneNumber	+1-555-0123
url, website, href	https://www.example.com/path
city	San Francisco
price, amount, total	42.99
createdAt, timestamp	2024-08-15T10:30:00Z
id, userId, orderId	d1b2f3a4-5678-9abc-... (UUID)
isActive, enabled	true / false
color, hexColor	#a3f29b

Field matching is case-insensitive and ignores separators — firstName, first_name, first-name, and FIRST_NAME all resolve to the same generator.

Tip

Semantic values intentionally bypass schema constraints for realism. A field named email with maxLength: 5 still gets an email address — the field name’s intent matters more than the constraint for mock data quality.

Faker fallback

Fields that don’t match any semantic pattern get type-valid faker output:

• Strings — random sentences, respecting minLength/maxLength and format (date-time, uri, email, uuid)
• Integers/Numbers — random values within minimum/maximum/exclusiveMinimum/exclusiveMaximum bounds
• Booleans — deterministic true/false based on the request seed
• Arrays — generated items respecting minItems/maxItems
• Objects — all required properties populated, optional properties included

Enhancing your spec with AI agents

If your spec is light on examples, you don’t have to add them manually. Mimikos provides an AI agent skill that reads your spec and source code, then enriches the spec with property-level examples, error responses, format annotations, and request body metadata — without restructuring anything.

The mimikos-enhance skill teaches AI coding assistants (Claude Code, Cursor, and similar tools) to:

1. Detect what your spec is missing (examples, error responses, formats)
2. Search your test fixtures and source code for realistic values
3. Apply mechanical enrichments with OAS standard citations for every change

The result: better mock responses from Mimikos, better documentation output, better code generation — all from a single spec improvement pass.

Getting the skill

Download the skill files from the Mimikos repository:

• SKILL.md — main skill instructions (required)
• examples.md — before/after enhancement examples (recommended)

Place the skill file in your AI tool’s configuration directory:

Tool	Location
Claude Code	.claude/commands/mimikos-enhance.md
Cursor	.cursor/rules/mimikos-enhance.mdc

Then ask your agent to “enhance my OpenAPI spec” or “improve my spec for Mimikos.” See the skill’s README for full setup instructions.

Determinism: same request, same response

Responses are seeded from a SHA-256 fingerprint of the request:

• HTTP method
• Path
• Query parameters (sorted)
• Request body (if present)

Change any of these, the response changes. Keep them the same, the response is identical — across restarts, across machines.

Per-field sub-seeding

Each field in the response is seeded independently from a combination of the request seed and the field’s path in the schema. This means adding or removing a field in your schema doesn’t change existing field values — only the new field gets a new value. This is critical for snapshot testing — schema evolution doesn’t cascade into unrelated field changes.

Request error responses

When Mimikos can’t serve a valid response for your request, you get RFC 7807 Problem Details with actionable diagnostics:

curl -X POST http://localhost:8080/pets \
  -H "Content-Type: application/json" \
  -d '{"invalid": true}'

{
  "type": "about:blank",
  "title": "Request validation failed",
  "status": 400,
  "detail": "1 validation error",
  "errors": [
    {
      "field": "/name",
      "message": "property 'name' is required"
    }
  ]
}

Explicit status codes

Request a specific error response defined in your spec using the X-Mimikos-Status header:

curl -H "X-Mimikos-Status: 404" http://localhost:8080/pets/42

Returns the 404 response defined in your spec’s schema for that endpoint, or an RFC 7807 fallback if no schema is defined.

Strict mode

By default, Mimikos logs a warning if a generated response fails schema validation but still sends it. Enable strict mode to return a 500 error instead:

mimikos start --strict petstore.yaml

Useful for catching schema issues during development — if your spec’s constraints make it impossible to generate a valid response, strict mode surfaces the problem immediately.