Using Wirespec as a DSL for Pact

[wilmveel]

As a follow up on a discussion on slack we start this discusion to see what the potential is to use Wirespec as a Domain Specific language to define Pact contracts.

Wirespec envisions a contract-first approach using simple, human-readable specifications. By acting as the single source of truth and generating aligned code for both producers and consumers, it prevents errors before development even begins.

This design-first methodology is a perfect match for Pact. While Wirespec defines the contract upfront, PactFlow continuously verifies that implementations never break it in a live CI/CD environment. Together, they create a powerful end-to-end workflow, reducing integration errors and providing unparalleled confidence in your APIs.

The Challenge: The Missing Link for Pact Compatibility

Currently, Wirespec excels at defining the shape and type of data in a contract (e.g., a userId is a String, a createdAt is a String with a date-time format). However, to generate a valid Pact contract, we need to provide two additional pieces of information that are central to how Pact works:

1. Example Values: Pact needs a concrete, realistic example of the data to generate a mock response for the consumer tests. Without an example, Pact wouldn't know what value to put for userId or productName.
2. Matchers: Relying on exact example values makes tests brittle. If an example userId is "12345", a consumer test will fail if the provider returns a different valid ID like "67890". Matchers solve this by defining the rule for a value (e.g., "must be a UUID," "must be a string that looks like an ISO date," or "must be an integer") rather than the exact value itself.

To bridge this gap, we propose extending the Wirespec DSL to incorporate these two concepts directly into the contract definition.

Proposed Solution: Extending the Wirespec DSL

We propose to solve this gap by enhancing Wirespec's core type system. The proposal is to allow refinement of primitive types, baking the validation rules directly into the type definitions. Also define defaults for the values direct in het type system.

type UUID -> String(/^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$/g) = "9c4d285d-ac79-4825-852c-c00b8b550fa9"
type Name -> String(/^[0-9a-zA-Z]{1,50}$/g) = "Jhon"
type DutchPostalCode -> String(/^([0-9]{4}[A-Z]{2})$/g) = "2871LA"
type Date -> String(/^([0-9]{2}-[0-9]{2}-20[0-9]{2})$/g) = "02-02-2022"

// These refined types are then composed into more complex types.
type Address {
  street: Name,
  houseNumber: Integer(0, 9999) = 122,
  postalCode: DutchPostalCode
}

type Person {
  firstname: Name,
  lastName: Name,
  age: Integer(0, 99) = 30,
  shoeSize: Number(14.5, 55.5) = 44.5
  address: Address
}

type Todo {
  id: UUID,
  person: Person,
  done: Boolean,
  prio: Integer(-5, 5) = 3
  date: Date
}

type Error {
  reason: String(/^.*{1,50}$/g) = "Cannot create todo"
}

This syntax elegantly solves the matcher requirement. A Wirespec-to-Pact generator can directly map these refined types to Pact's matching rules.

Wirespec Refined Type	Generated Pact Matcher
String(/...regex.../)	A regex matcher with the provided pattern.
Integer(min, max)	An integer type matcher. The range becomes a provider-side validation.
Number(min, max)	A number type matcher. The range becomes a provider-side validation.

Example

This shows how the wirespec dsl would translate to the Pact JS DSL

// Using Pact JS V3+ syntax (@pact-foundation/pact)
import { Matchers } from '@pact-foundation/pact';

// =================================================================
// 1. Define Reusable Matchers from Wirespec Refined Types
// =================================================================
// While not strictly necessary, this makes the final specification
// much cleaner and more readable.

const uuidMatcher = Matchers.regexp(
  "9c4d285d-ac79-4825-852c-c00b8b550fa9",
  /^[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}$/i // Note: added 'i' for case-insensitivity, common for UUIDs
);

const nameMatcher = Matchers.regexp(
  "Jhon",
  /^[0-9a-zA-Z]{1,50}$/
);

const dutchPostalCodeMatcher = Matchers.regexp(
  "2871LA",
  /^([0-9]{4}[A-Z]{2})$/
);

const dateMatcher = Matchers.regexp(
  "02-02-2022",
  /^([0-9]{2}-[0-9]{2}-20[0-9]{2})$/
);

// =================================================================
// 2. Translate Composite Wirespec Types into Pact Body Specifications
// =================================================================

// Translation of 'type Address'
const addressBody = Matchers.like({
  street: nameMatcher,
  houseNumber: Matchers.integer(122), // Range is a business rule, not checked by Pact
  postalCode: dutchPostalCodeMatcher,
});

// Translation of 'type Person' which nests 'Address'
const personBody = Matchers.like({
  firstname: nameMatcher,
  lastName: nameMatcher, // Can reuse the same matcher with its example
  age: Matchers.integer(30),
  shoeSize: Matchers.decimal(44.5),
  address: addressBody, // Nesting the translated Address object
});

// --- Main Success Payload: The 'Todo' object ---
export const todoSuccessBody = Matchers.like({
  id: uuidMatcher,
  person: personBody,
  done: Matchers.boolean(false), // Providing a concrete example
  prio: Matchers.integer(3),
  date: dateMatcher,
});


// --- Error Payload: The 'Error' object ---
export const errorBody = Matchers.like({
  reason: Matchers.regexp(
    "Cannot create todo",
    /^.{1,50}$/ // Simplified the regex from the example
  ),
});

[wilmveel]

To further simplify the DSL, we could consider making the explicit default values (= "...") optional. Instead, a Wirespec-to-Pact generator could automatically create example values using a seeded reverse regex generator (rgxgen).

This approach removes the burden of manually defining and maintaining examples, while guaranteeing the example always matches its own validation rule. Using a consistent seed ensures deterministic output, which is crucial for stable contract tests across consumer and provider builds.

The Flock community's kotlin-rgxgen is a great proof-of-concept for this capability. It would make the Wirespec definitions even more concise and robust.

[mefellows]

Thanks for raising this and fleshing it out. I'll aim to come back next week with some further thoughts, but wanted to "ack" this for now.