wiremock.yaml Configuration Reference

The wiremock.yaml file is used by the WireMock CLI to configure local mock services. It defines service configurations including HTTP/HTTPS ports, TLS certificates, API types, and cloud synchronization settings.

File location

The wiremock.yaml file should be placed in your WireMock working directory (typically .wiremock by default, or as specified with the --wiremock-dir argument).

Schema validation

The configuration file conforms to the JSON Schema specification available at: https://static.wiremock.io/schemas/wiremock.yaml-schema.json

Root structure

global:
  # Global configuration (optional)
services:
  # Service definitions (required)

Global configuration

The global section contains configuration that applies to all services by default.

Global HTTPS settings

global:
  https:
    certificate:
      # Certificate configuration (see Certificate Configuration section)

When a global certificate is configured, all services with an https section will use it by default unless they specify their own certificate.

Services

The services section is a map of service names to their configurations. Service names are user-defined identifiers.

services:
  my-service-name:
    # Service configuration
  another-service:
    # Service configuration

Required service properties

Each service must define these properties:

type

The type of mock API.

Type: string
Required: Yes
Valid values: REST, Unstructured, gRPC, GraphQL (case insensitive)

type: REST

name

Human-readable name for the service.

Type: string
Required: Yes

name: "Invoicing API"

port

HTTP port number for the service.

Type: integer
Required: Yes (or https must be provided)
Valid range: 1-65535

port: 8080

Optional service properties

description

Optional description of the service.

Type: string
Required: No

description: "Mock API for the invoicing system"

cloud_id

WireMock Cloud mock API ID for syncing with cloud.

Type: string
Required: No
Pattern: 4-15 lowercase alphanumeric characters

cloud_id: abc123xyz

This field is automatically populated when pulling a mock API from WireMock Cloud.

path

Path to the directory containing stub mappings, files, and API specifications. The path is relative to the location of wiremock.yaml.

Type: string
Required: No

path: ./my-service

This directory typically contains items needed to run the service. For example:

stub-mappings.yaml - Stub mapping yaml file
schema.graphql or openapi.yaml - Mock API IDL documents such as OpenAPI/GraphQL schema

open_api

OpenAPI-specific configuration for validation.

Type: object
Required: No

open_api:
  validation_mode: soft

Properties:

validation_mode - Controls OpenAPI request/response validation
- Type: string
- Valid values: none, soft, hard
- Default: none
- none - No validation
- soft - Validation warnings logged but requests not rejected
- hard - Invalid requests are rejected

https

HTTPS configuration for the service. See the TLS/HTTPS Configuration section below.

Type: object
Required: No (but either port or https must be provided)

https:
  port: 8443
  certificate:
    pem: /path/to/cert.pem

originals

Map of original service URLs for recording and proxying.

Type: object
Required: No

originals:
  default: https://api.example.com
  staging: https://staging-api.example.com

The keys in this map can be referenced when using recording features to specify which target service to record from.

TLS/HTTPS configuration

Services can be configured to run over HTTPS using TLS certificates. TLS can be configured globally (for all services) or per-service.

HTTPS service configuration

services:
  my-service:
    type: REST
    name: "Secure API"
    https:
      port: 8443
      certificate:
        # Certificate configuration

Properties:

port - HTTPS port number (required, 1-65535)
certificate - Certificate configuration (optional, inherits from global if not specified)

Certificate configuration

Certificates can be configured in three ways:

PEM file

A PEM-encoded file containing both the RSA private key and X509 certificate.

certificate:
  pem: /path/to/certificate.pem

The path can be absolute or relative to the wiremock.yaml file. PEM file format:

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDHIpsyRDeM1lFQ
... (base64-encoded content)
GhxuZ3ceXiqwvhH8Yt5gNs0=
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIDrzCCApegAwIBAgIUR24W6NZN7xPwSqc59usFQ37HPYswDQYJKoZIhvcNAQEL
... (base64-encoded content)
dHhXPaefkEhrsUbnXGYRfwQhf4SzdYCMCJno7KKsNn6RLIo=
-----END CERTIFICATE-----

PKCS12 or JKS keystore

A keystore file (PKCS12 or JKS format) containing the private key and certificate.

certificate:
  keystore: /path/to/keystore.p12
  password: very_secret
  alias: my_cert  # optional

Properties:

keystore - Path to the keystore file (absolute or relative to wiremock.yaml)
password - Password to unlock the keystore (required)
alias - Optional alias to select a specific certificate if the keystore contains multiple entries. If omitted, the first entry is used.

Certificate alias reference

When a global keystore is configured, individual services can reference specific certificates by alias:

global:
  https:
    certificate:
      keystore: /path/to/keystore.p12
      password: very_secret

services:
  service-one:
    type: REST
    name: "Service One"
    https:
      port: 8443
      certificate:
        alias: service_one_cert

  service-two:
    type: REST
    name: "Service Two"
    https:
      port: 8444
      certificate:
        alias: service_two_cert

Default self-signed certificate

If no certificate is configured, services will use WireMock’s default self-signed certificate.

Profiles

Configuration overrides can be defined in profile files named wiremock-<profile-name>.yaml. These files overlay the base configuration when running commands with the --profile/-p flag. See Managing Environments for more information about using profiles to manage environments in WireMock Cloud.

Complete example

global:
  https:
    certificate:
      keystore: /etc/wiremock/certs/global-keystore.p12
      password: global_password
      alias: default_cert

services:
  invoicing-api:
    type: REST
    name: "Invoicing API"
    description: "Mock API for invoicing system"
    cloud_id: ndzew
    port: 8080
    https:
      port: 8443
    path: ./invoicing-api
    open_api:
      validation_mode: soft
    originals:
      default: https://api.example.com/invoicing

  payment-api:
    type: REST
    name: "Payment API"
    cloud_id: wroog
    port: 8081
    https:
      port: 8444
      certificate:
        alias: payment_cert
    path: ./payment-api

  graphql-service:
    type: GraphQL
    name: "GraphQL Gateway"
    port: 9090
    path: ./graphql-gateway
    originals:
      default: https://graphql.example.com

  grpc-service:
    type: gRPC
    name: "gRPC Service"
    https:
      port: 50051
      certificate:
        pem: ./certs/grpc-service.pem
    path: ./grpc-service

​File location

​Schema validation

​Root structure

​Global configuration

​Global HTTPS settings

​Services

​Required service properties

​type

​name

​port

​Optional service properties

​description

​cloud_id

​path

​open_api

​https

​originals

​TLS/HTTPS configuration

​HTTPS service configuration

​Certificate configuration

​PEM file

​PKCS12 or JKS keystore

​Certificate alias reference

​Default self-signed certificate

​Profiles

​Complete example

​See also

File location

Schema validation

Root structure

Global configuration

Global HTTPS settings

Services

Required service properties

type

name

port

Optional service properties

description

cloud_id

path

open_api

https

originals

TLS/HTTPS configuration

HTTPS service configuration

Certificate configuration

PEM file

PKCS12 or JKS keystore

Certificate alias reference

Default self-signed certificate

Profiles

Complete example

See also