Suppression Discussion

Problem

Let's assume that we will get a "Added_minLength" violation here that we want to ignore. The original Swagger didn't mention the constraint on name, and we already know that this is fine. We need to suppress this diff.

The TypeSpec-generated Swagger looks like:

{
  "definitions": {
    "Foo": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "name"
      ]
    }
  }
}

We have a few options for targeting the suppression:

1. Suppress the "Added_minLength" group
2. Target the Swagger path
3. Target the transformation path

Option 1: Suppress the Group

This would be the easiest thing to do, but has the problem that would be very easy to suppress too much. Simply suppressing this group would include suppressing cases where the value was more than 1 (for example 100) that probably would impact the validity of the service definition.

Even using a rule suppress only where minLength = 1 would catch all such cases on properties other than name, when you only intended to suppress the violation on name.

For this reason, this approach is non-ideal.

Option 2: Target the Swagger Path

The Swagger path here would be definitions.Foo.properties.name.minLength. The benefit here is that because rest-api-diff expands references in place during the transformation, it would be possible to propagate the suppression as well. The downside is that this would likely be the most difficult to implement.

It should only be necessary to target the path.

Option 3: Target the Transformation Path

The transformation path here would be quite long, something like: paths.getFoo.get.responses.200.schema.properties.name.minLength. The benefit is that this should be straightforward to suppress, but the downsides are that the paths are long and if Foo is referenced in several places, you would need several long path names to target them. For example, if Foo were also a body parameter in a PUT, as well as the return type for that operation, you'd need the following suppressions:

paths.getFoo.get.responses.200.schema.properties.name.minLength paths.createFoo.put.parameters.body.schema.properties.name.minLength paths.createFoo.put.responses.200.schema.properties.name.minLength

This would become quite cumbersome and confusing. It would also require the user to navigate the diff.json file to construct the path, when it would likely be more natural to navigate the source Swagger structure.