Policy Checks JSON Object

By default, Liquibase sends output to the console in a human-readable text format. By contrast, JSON (JavaScript Object Notation) is a text syntax designed to be easily understood by computers. If your application needs to access information about policy checks, specify json as the value for the format attribute when you run policy checks commands on your database. This way, your application can easily parse through the Liquibase output.

You can format the output of Policy Checks like run and show as a JSON object. You need a valid Liquibase Pro License Key to do this.

Syntax

Tip: For best results, specify all commands and parameters in the --kebab-case format in the CLI. If your preference is camelCase, it also works in the CLI.

Using the CLI, to send JSON output to STDOUT:

liquibase checks run --format=json --check-name=<checkShortName>

To send JSON output to a file:

liquibase checks run --format=json --check-name=<checkShortName> --output-file=path/to/myOutput.json

To send text output to STDOUT:

liquibase checks run --format=txt --check-name=<checkShortName>

If you do not specify a value for format, Liquibase sends text output to STDOUT. For more information about setting the different types of parameters—the CLI, flow files, properties files, and environment variables—see Liquibase Parameters.

Object format

The root schema of the JSON object is called checks and includes the following properties and subschemas:

  • executionDate (string)
  • returnCode (int)
  • changesetsValidatedCount (int)
  • executedChecksCount (int)
  • issueCount (int)
  • unparseableChangesetsCount (int)
  • unlicensedChangesetsCount (int)
  • hasProLicense (boolean)
  • changelogFilePath (string)
  • username (string)
  • productVersion (string)
  • integration (string)
  • issues (array of JSON objects)
    • changesetAuthor (string)
    • changesetFilePath (string)
    • changesetId (string)
    • checkMessage (string)
    • checkName (string)
    • checkReturnCode (int)
    • checkSeverity (string)
    • checkShortName (string)
  • changesetsValidated (array of JSON objects)
    • author (string)
    • filepath (string)
    • id (string)
  • executedChecks (array of JSON objects)
    • checkName (string)
    • checkShortName (string)
    • description (string)
    • enabled (boolean)
    • severity (string)

If you run liquibase checks run --format=json --check-name=ChangesetCommentCheck, Liquibase displays the following output:

{
  "checks": {
    "executionDate": "2022-03-04T20:37:33.467461Z",
    "returnCode": 0,
    "changesetsValidatedCount": 3,
    "executedChecksCount": 1,
    "issueCount": 3,
    "unparseableChangesetsCount": 0,
    "unlicensedChangesetsCount": 0,
    "hasProLicense": true,
    "changelogFilePath": "custom-changelog.sql",
    "username": "liquibase-user",
    "productVersion": "Liquibase 4.9.0",
    "integration": "cli",
    "issues": [
      {
        "changesetAuthor": "your.name",
        "changesetFilePath": "custom-changelog.sql",
        "changesetId": "1",
        "checkMessage": "Liquibase recommends that authors include comments about the purpose and impact of a changeset in <comment> elements to prevent the development of undocumented or siloed knowledge and ensure that the purpose of a given changeset is easily understood by other people who use this changelog.",
        "checkName": "Changesets Must Have a Comment Assigned",
        "checkReturnCode": 0,
        "checkSeverity": "INFO",
        "checkShortName": "ChangesetCommentCheck"
      },
      {
        "changesetAuthor": "your.name",
        "changesetFilePath": "custom-changelog.sql",
        "changesetId": "2",
        "checkMessage": "Liquibase recommends that authors include comments about the purpose and impact of a changeset in <comment> elements to prevent the development of undocumented or siloed knowledge and ensure that the purpose of a given changeset is easily understood by other people who use this changelog.",
        "checkName": "Changesets Must Have a Comment Assigned",
        "checkReturnCode": 0,
        "checkSeverity": "INFO",
        "checkShortName": "ChangesetCommentCheck"
      },
      {
        "changesetAuthor": "other.dev",
        "changesetFilePath": "custom-changelog.sql",
        "changesetId": "3",
        "checkMessage": "Liquibase recommends that authors include comments about the purpose and impact of a changeset in <comment> elements to prevent the development of undocumented or siloed knowledge and ensure that the purpose of a given changeset is easily understood by other people who use this changelog.",
        "checkName": "Changesets Must Have a Comment Assigned",
        "checkReturnCode": 0,
        "checkSeverity": "INFO",
        "checkShortName": "ChangesetCommentCheck"
      }]
    ,
    "changesetsValidated": [
      {
        "author": "your.name",
        "filepath": "custom-changelog.sql",
        "id": "1"
      },
      {
        "author": "your.name",
        "filepath": "custom-changelog.sql",
        "id": "2"
      },
      {
        "author": "other.dev",
        "filepath": "custom-changelog.sql",
        "id": "3"
      }]
    ,
    "executedChecks": [
      {
        "checkName": "Changesets Must Have a Comment Assigned",
        "checkShortName": "ChangesetCommentCheck",
        "description": "This check enforces the Liquibase recommendation that comments be added to each changeset to document the purpose of a changeset for other/future consumers of this changelog",
        "enabled": true,
        "severity": "0"
      }]

  }
}

Related links