Review of pact-json-schema v2 about pact-specification

[BenSayers]

I released a new version of the schema incorporating all your feedback, thanks for the help @bethesque and @uglyog!

https://bitbucket.org/atlassian/pact-json-schema/src/8d0b9d2f38fe517dfbce0e5d0b8755eaefaacb5b/schemas/v2/schema.json?at=master&fileviewer=file-view-default

[BenSayers]

And just for fun is this a valid pact file?

{
    "consumer": {
        "name": "A consumer"
    },
    "interactions": [],
    "metadata": {
        "pactSpecificationVersion": "2.0.0",
        "pact-specification": {
            "version": "2.0.0"
        },
        "pactSpecification": {
            "version": "2.0.0"
        }
    },
    "provider": {
        "name": "A provider"
    }
}

[bethesque]

You've convinced me. Put all 3 in. Document our appalling lack of coordination...

[bethesque]

@uglyog is match=equality a thing you've added in a later version, or in jvm? I've not used it before.

https://bitbucket.org/atlassian/pact-json-schema/src/8c17153c5658b9e2dff8404c7cc3751fe3e9ebdd/schemas/v2/schema.json?at=master&fileviewer=file-view-default#schema.json-48

[bethesque]

@BenSayers if you want to use the official terminology (which I'm regretting now!), it's "pacticipant".

[bethesque]

There is also the metadata which I believe we decided should look like

"metadata": {
  "pactSpecification": {
    "version": "1.2.3"
  }
}

but I think the pact-jvm still uses pact-specification.

[BenSayers]

@bethesque I got the equality matcher from the docs here:
https://github.com/pact-foundation/pact-specification/tree/version-2#supported-matchers

I'm hunting for a test case that uses it but haven't found one yet...

[uglyog]

The equality matcher is used to reset matching when like matchers cascade in the JVM version. But it is the default matching when no matcher is specified, so not supporting it has no effect.

[BenSayers]

The equality matcher is mentioned as a new feature in the v3 docs. So I propose we remove it from the v2 docs in this project and I'll remove it from the v2 json schema as well.

https://github.com/pact-foundation/pact-specification/tree/version-3#add-an-equality-matcher

[BenSayers]

Here are all the variations of metadata I could find amongst our pact files:

    "metadata": {
        "pactSpecificationVersion": "2.0.0"
    },

    "metadata": {
        "pact-specification": {
            "version": "2.0.0"
        },
        "pact-jvm": {
            "version": "3.2.6"
        }
    },

    "metadata": {
        "pactSpecification": {
            "version": "2.0.0"
        }
    },

And some of our pact files don't have a metadata property at all. So I could add a definition of this to the schema but it would have to be an optional property defined as a "oneOf" operation with the schemas for the 3 variations. Let me know if you think that's a useful thing to have in the schema and I'll add it.

[bethesque]

Please add the metadata, and set it to the last example. It's what we should all move to. If it's going to fail in annoying ways, just make it optional.

[BenSayers]

I have mixed feelings about only adding the 1 variation. I like that it sets a single standard to move toward, but arguably that is the job of future versions of the specification.

Including all 3 variations we would be documenting what you will actually find if you are looking at the metadata property of v2 pact files. For example if I wanted to write code to read the pact specification version of every pact file in our broker I would have to handle the fact these variations exist.

Thoughts?

[uglyog]

I have no idea how the JVM version ended up with hyphenated keys, that is so un-JVM to do that :-D

[BenSayers]

Is this a valid pact file?

{
    "consumer": {
        "name": "A consumer"
    },
    "interactions": [],
    "metadata": {},
    "provider": {
        "name": "A provider"
    }
}

I'm trying to decide how strict I should be about the metadata definition. Should we require that if you have a metadata property defined it must contain the version number in one of the three variations?

[uglyog]

The most basic pact file is:

{
    "consumer": {
        "name": "A consumer"
    },
    "interactions": [],
    "provider": {
        "name": "A provider"
    }
}

The metadata should be optional, and it should allow any key-value pairs.

[BenSayers]

I agree with all of that, but that doesn't answer my question.

[uglyog]

Yes it is, an empty metadata section is valid

[uglyog]

Yes, it would be

[bethesque]

We should probably stick it in the pact specification repo somewhere.

[BenSayers]

I’m open to it but keep in mind it has a hundred or so tests and a release process that go with it.

[bethesque]

Let's put a link to it then. Is there a "home page" for it, or should we just link to the file?

[BenSayers]

Yep, the home page is here:
https://bitbucket.org/atlassian/pact-json-schema

[bethesque]

I've added it here: https://github.com/pact-foundation/pact-specification/blob/master/README.md#index

[bethesque]

Thanks for your work on this @BenSayers

[BenSayers]

No worries.

Fun side note: I've been playing around with generating Pact type definitions off this schema as a way of keeping tooling written in strongly typed languages consistent when it comes to working with Pact files. The only part of the schema that isn't very type system friendly is MatchingRules because I used pattern properties.

Heres a typescript example

/**
* This file was automatically generated by json-schema-to-typescript.
* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
* and run json-schema-to-typescript to regenerate this file.
*/

export type Interactions = Interaction[];

/**
 * Schema for a Pact file
 */
export interface Pact {
  consumer: Pacticipant;
  interactions: Interactions;
  metadata?: Metadata;
  provider: Pacticipant;
  [k: string]: any;
}
export interface Pacticipant {
  name: string;
  [k: string]: any;
}
export interface Interaction {
  description: string;
  providerState?: string;
  request: Request;
  response: Response;
}
export interface Request {
  body?: any;
  headers?: Headers;
  matchingRules?: MatchingRules;
  method: ("connect" | "CONNECT" | "delete" | "DELETE" | "get" | "GET" | "head" | "HEAD" | "options" | "OPTIONS" | "post" | "POST" | "put" | "PUT" | "trace" | "TRACE");
  path: string;
  query?: string;
}
export interface Headers {
  [k: string]: string;
}
export interface MatchingRules {

}
export interface Response {
  body?: any;
  headers?: Headers;
  matchingRules?: MatchingRules;
  status: number;
}
export interface Metadata {
  pactSpecification?: {
    version: string;
  };
  pactSpecificationVersion?: string;
  "pact-specification"?: {
    version: string;
  };
  [k: string]: any;
}

If patternProperties is switched to additionalProperties the MatchingRules comes out like this:

export interface MatchingRules {
  [k: string]: ({
    match: "type";
    max?: number;
    min?: number;
  } | {
    match: "regex";
    regex: string;
  });
}

I'll see how other languages generators handle that OR in the MatchingRules definition and maybe throw these definitions into swagger-mock-validator and see what happens.