The V4 Specification Retrospectively Alters the V3 Specification for Matchers and Generators

[adamrodger]

The v4 specification details a number of supported matchers along with which version that they are supported from.

However, it says that a number of these matchers are supported in the v3 specification, even though that specification makes no mention of them.

This has caused confusion for users, who expect implementations that support up to v3 to support these additional matchers. For example, v4 says that v3 supports matchers for date, time, content type, boolean and multi-value, but it doesn't. These may be de-facto supported by the reference implementation, but the idea of the spec is that alternative implementations could be created as long as they conform to the spec, and this ambiguity currently makes that impossible.

Edit: It does the same thing for generators also. For example it says that v3 supports generators for Provider State and Mock Server URL, but v3 has no mention of these.

[rholshausen]

I have corrected the V3 readme with the missing matchers.

[adamrodger]

I'm not really sure if that's the right thing to do...? Anything that said it was V3 compliant before has now been made retrospectively non-compliant.

Shouldn't we issue new spec versions or something once they've been published?

[bethesque]

Could we do a 3.1 version?

[rholshausen]

Creating a new version is not going to provide much benefit.

The matchers and generators were designed to be extensible so that new ones can be added at any time. They are not tied to the spec version, because their format has not changed since V3.

Those matchers have always existed in Pact-JVM as part of V3, they were just missing from the V3 readme. The Rust core also supports them.

Two new matchers (Provider State and Mock Server URL) were added in 2019-2020 to support the needs of some users. I have left them documented as V4, but they are not tied to that as they pre-dated it. Both Pact-JVM and the Pact-Rust core will support them, even with V2 formatted Pact files.

The only matcher that has changed the format is the new V4 Array Contains one, because it requires it's own set of matchers and generators and is thus a recursive data structure. However, nothing has limited the attributes of a matcher to be a primitive value, so it can also be encoded into a V2 Pact file because the only requirement is to be persisted as JSON.

[adamrodger]

Perhaps I've not got my point across properly there.

What I'm saying is that you can't modify the spec according to what the reference implementation does. Specs are supposed to be immutable once published, even if there's a reference implementation, so that other implementations could be made which are compliant with that spec. That means changing a spec after it's published shouldn't happen, otherwise alternative implementations can never confidently declare compatibility.

It'd be like saying that Apache supports something so we'll go back and change the HTTP spec. That would be unfair to all the other HTTP servers out there.

You can produce a new version of the spec, obviously, but specs themselves should be immutable.

In this particular instance, PactNet has declared v3 compatibility for matchers, only now the spec has been changed so that's no longer true. From a user's perspective, PactNet is now claiming something that isn't true. From PactNet's perspective, it was true when the claim was made, it's just that the spec has changed since then (which isn't fair on PactNet).

[mefellows]

I totally get the point Adam. I think there is a gap in the specification, at least with how it works in practice.

My understanding is that the specification covers two things:

1. The structure of the pact file itself
2. How matching rules are applied

The matchers and generators were designed to be extensible so that new ones can be added at any time. They are not tied to the spec version, because their format has not changed since V3.

This is where the grey area begins. This certainly isn't clear in the summary of the specification - it seems the spec is agnostic to certain features that may or may not be present in the pact file (in this case, matchers/generators).

If the goal of the specification is to govern how matching rules are applied (2), how would this work for extensible matching rules where the rules can't be known in advance?

Without making a judgement call either way, this does add an additional complexity with understanding compatibility across implementations - each version / language would need to both be able to read X version of the spec AND be able to understand any extension points (such as matchers/generators).