JSON Reporter

Extension: revapi.reporter.json

This extension outputs the differences as JSON to some file or standard output.

Usage

Revapi needs to be configured to use this extension, it is not present by default. In case of maven plugin, you need to add the extension as a dependency of the maven plugin like so:

<build>
  ...
  <plugin>
    <groupId>org.revapi</groupId>
    <artifactId>revapi-maven-plugin</artifactId>
    <version>...</version>
    <dependencies>
      <dependency>
        <groupId>org.revapi</groupId>
        <artifactId>revapi-reporter-json</artifactId>
        <version>...</version>
      </dependency>
      ...
    </dependencies>
    <configuration>
      <analysisConfiguration>
        <revapi.reporter.json>
          ... configure the extension here ...
        </revapi.reporter.json>
      </analysisConfiguration>
    </configuration>
  </plugin>
  ...
</build>

Sample Configuration

[
  {
    "extension": "revapi.reporter.json",
    "configuration": {
      "minSeverity": "POTENTIALLY_BREAKING",
      "minCriticality": "documented",
      "output" : "out",
      "indent": false,
      "append": false,
      "keepEmptyFile": true
    }
  }
]

<analysisConfiguration>
  <revapi.reporter.json>
    <minSeverity>POTENTIALLY_BREAKING</minSeverity>
    <minCriticality>documented</minCriticality>
    <output>out</output>
    <indent>false</indent>
    <append>false</append>
    <keepEmptyFile>true</keepEmptyFile>
  </revapi.reporter.json>
</analysisConfiguration>

Properties

minSeverity: The minimum severity of problems that will be included in the output. Possible values are EQUIVALENT, NON_BREAKING, POTENTIALLY_BREAKING and BREAKING. At least one of minSeverity and minCriticality should be specified.
minCriticality: The minimum criticality of problems that will be included in the output. The possible values are the ones defined in the pipeline configuration of the analysis. By default, these are allowed, documented, highlight and error.
output: The path to the output file. Two special values are recognized: out (which is the default value of this property) and err which represent standard output or standard error output respectively.
append: Whether to append to the chosen output or whether to overwrite it (doesn’t make sense for standard (error) output). The default value is false meaning the output file will be overwritten if it already exists.
keepEmptyFile: Defaults to true. If true the output file is kept even if no reports were written to it and thus it is empty. Has no effect if append is set to true.
indent: Whether to indent the JSON or leave it in the minimal form. false by default to produce minimal output.

Output Format

The JSON report generated by this extension conforms to the following schema.

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "The Revapi check code identifying the found problem."
      },
      "old": {
        "type": "string",
        "description": "The textual representation of the element in the old API"
      },
      "new": {
        "type": "string",
        "description": "The textual representation of the element in the new API"
      },
      "name": {
        "type": "string",
        "description": "The name of the problem in a human readable form"
      },
      "description": {
        "type": "string",
        "description": "The description of the found problem in a human readable form"
      },
      "classification": {
        "type": "array",
        "description": "The classification of the problem",
        "items": {
          "type": "object",
          "properties": {
            "compatibility": {
              "type": "string",
              "description": "The type of the compatibility this problem breaks",
              "enum": ["BINARY", "SOURCE", "SEMANTIC", "OTHER"]
            },
            "severity": {
              "type": "string",
              "description": "The severity of the problem for given compatibility type",
              "enum": ["EQUIVALENT", "NON_BREAKING", "POTENTIALLY_BREAKING", "BREAKING"]
            }
          }
        }
      },
      "attachments": {
        "type": "array",
        "description": "The attachments of the difference that the analyzer added to further identify and describe the problem",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the attachment"
            },
            "value": {
              "type": "string",
              "description": "The value of the attachment"
            }
          }
        }
      }
    }
  }
}

An example report might therefore look something like this.

[
  {
    "code": "java.method.addedToInterface",
    "old": null,
    "new": "method void com.acme.diy.Toolbox::addHammer()",
    "name": "method added to interface",
    "description": "Method was added to an interface.",
    "classification": [
      {
        "compatibility": "BINARY",
        "severity": "NON_BREAKING"
      },
      {
        "compatibility": "SOURCE",
        "severity": "BREAKING"
      },
      {
        "compatibility": "SEMANTIC",
        "severity": "POTENTIALLY_BREAKING"
      }
    ],
    "attachments": [
      {
        "name": "package",
        "value": "com.acme.diy"
      },
      {
        "name": "classQualifiedName",
        "value": "com.acme.diy.Toolbox"
      },
      {
        "name": "classSimpleName",
        "value": "Toolbox"
      },
      {
        "name": "methodName",
        "value": "addHammer"
      },
      {
        "name": "newArchive",
        "value": "com.acme:toolbox:jar:1.1-SNAPSHOT"
      },
      {
        "name": "elementKind",
        "value": "method"
      },
    ]
  }
]