Revapi JSON Reporter

Super simple Revapi reporter outputting a JSON representation of the differences to a file or on standard output.

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",
      "output" : "out",
      "indent": false,
      "append": false
    }
  }
]
<analysisConfiguration>
  <revapi.reporter.json>
    <minSeverity>POTENTIALLY_BREAKING</minSeverity>
    <output>out</output>
    <indent>false</indent>
    <append>false</append>
  </revapi.reporter.json>
</analysisConfiguration>

Properties

minSeverity

The minimum severity of problems that will be included in the output. If not specified, defaults to POTENTIALLY_BREAKING. Possible values are NON_BREAKING, POTENTIALLY_BREAKING and BREAKING.

output

The path to the output file. Two special values are recongized: 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.

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"
      },
    ]
  }
]

Back to top

Msb3 Maven skin by Marek Romanowski.