witness.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "format-version": {
      "description": "Version of the format.",
      "const": "0.1"
    },
    "producer": {
      "description": "Producer. Could be a tool, a human or something else.",
      "type": "object",
      "required": [
        "name",
        "version"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the producer."
        },
        "version": {
          "type": "string",
          "description": "Version of the producer."
        },
        "configuration": {
          "type": "string",
          "description": "Configuration of the producer. Should be used to distinguish different configurations of the same version of the producer."
        },
        "description": {
          "type": "string",
          "description": "Additional description about the producer. Could be used for any information that does not fit into any of the other producer properties."
        },
        "command_line": {
          "type": "string",
          "description": "Bash-compliant command line used to produce the entry. Should be used to improve reproducibility."
        }
      }
    },
    "hash": {
      "type": "string",
      "description": "SHA-256 hash.",
      "pattern": "[0-9a-fA-F]{64}"
    },
    "entry-uuid": {
      "type": "string",
      "description": "Unique identifier of the entry ([RFC4122](https://www.ietf.org/rfc/rfc4122.txt) defines the UUID format).",
      "format": "uuid"
    },
    "task": {
      "description": "Verification task.",
      "type": "object",
      "required": [
        "input_files",
        "input_file_hashes",
        "specification",
        "data_model",
        "language"
      ],
      "properties": {
        "input_files": {
          "description": "Files belonging to the verification task that were given as input to the producer.",
          "type": "array",
          "items": {
            "type": "string",
            "description": "Bash-compliant file name pattern, which must represent _exactly one_ file."
          }
        },
        "input_file_hashes": {
          "type": "object",
          "description": "SHA-256 hashes of each file in `input_files`. Every file name pattern listed in `input_files` must appear as a key.",
          "additionalProperties": {
            "$ref": "#/$defs/hash"
          }
        },
        "specification": {
          "type": "string",
          "description": "Specification in [SV-COMP format](https://sv-comp.sosy-lab.org/2022/rules.php) against which the verification is done."
        },
        "data_model": {
          "description": "Data model to be assumed for the task.",
          "enum": [
            "ILP32",
            "LP64"
          ]
        },
        "language": {
          "description": "Source language of the input files.",
          "type": "string",
          "examples": [
            "C",
            "Java"
          ]
        }
      }
    },
    "metadata": {
      "description": "Information that identifies the entry and describes the context of its production.",
      "type": "object",
      "required": [
        "format_version",
        "uuid",
        "creation_time",
        "producer",
        "task"
      ],
      "properties": {
        "format_version": {
          "$ref": "#/$defs/format-version",
          "description": "Version of the format of the entry."
        },
        "uuid": {
          "$ref": "#/$defs/entry-uuid"
        },
        "creation_time": {
          "type": "string",
          "description": "Date and time in ISO8601 format when the entry (not the file) was created.",
          "format": "date-time"
        },
        "producer": {
          "$ref": "#/$defs/producer",
          "description": "Producer of the entry."
        },
        "task": {
          "$ref": "#/$defs/task",
          "description": "Verification task for which the entry was produced."
        }
      }
    },
    "metadata-certificate": {
      "description": "Information that identifies the certificate entry and describes the context of its production.",
      "type": "object",
      "required": [
        "format_version",
        "uuid",
        "creation_time",
        "producer"
      ],
      "properties": {
        "format_version": {
          "$ref": "#/$defs/format-version",
          "description": "Version of the format of the certificate entry."
        },
        "uuid": {
          "$ref": "#/$defs/entry-uuid"
        },
        "creation_time": {
          "type": "string",
          "description": "Date and time in ISO8601 format when the certificate entry (not the file or target entry) was created.",
          "format": "date-time"
        },
        "producer": {
          "$ref": "#/$defs/producer",
          "description": "Producer of the certificate entry."
        }
      }
    },
    "location": {
      "description": "Location in the source code.",
      "type": "object",
      "required": [
        "file_name",
        "file_hash",
        "line",
        "column",
        "function"
      ],
      "properties": {
        "file_name": {
          "type": "string",
          "description": "Name of the file. Must be present in `task.input_files`."
        },
        "file_hash": {
          "$ref": "#/$defs/hash",
          "description": "SHA-256 hash of the file."
        },
        "line": {
          "type": "integer",
          "description": "Line in the file (starting with 1).",
          "minimum": 1
        },
        "column": {
          "type": "integer",
          "description": "Column in the file (starting with 0). Column 0 refers to the very beginning of the line (before any characters).",
          "minimum": 0
        },
        "function": {
          "type": "string",
          "description": "Name of the surrounding function."
        }
      }
    },
    "variable-identifier": {
      "type": "string",
      "pattern": "[_a-zA-Z][_a-zA-Z0-9]*",
      "description": "A valid C identifier used as name of a variable."
    },
    "branching-constraint": {
      "description": "Branching constraint analogous to branching waypoints in violation witnesses.",
      "type": "object",
      "required": [
        "constraint"
      ],
      "properties": {
        "constraint": {
          "type": "object",
          "required": [
            "value"
          ],
          "properties": {
            "value": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "invariant": {
      "description": "Invariant.",
      "type": "object",
      "required": [
        "string",
        "type",
        "format"
      ],
      "properties": {
        "string": {
          "type": "string",
          "description": "The invariant itself."
        },
        "type": {
          "description": "Interpretation of `string`. The following values are supported:\n\n* `assertion`: Assertion, e.g. `assert(<string>)` in C, inserted at the specified location. The insertion is hypothetical and doesn't affect other locations.",
          "enum": [
            "assertion"
          ]
        },
        "format": {
          "description": "Format of `string`. The following values are supported:\n\n* `C`: Expression in C language.",
          "enum": [
            "C"
          ]
        }
      }
    },
    "target": {
      "description": "Target entry of certification.",
      "type": "object",
      "required": [
        "uuid",
        "type",
        "file_hash"
      ],
      "properties": {
        "uuid": {
          "$ref": "#/$defs/entry-uuid",
          "description": "Unique identifier of the target entry."
        },
        "type": {
          "type": "string",
          "description": "`entry_type` of the target entry."
        },
        "file_hash": {
          "$ref": "#/$defs/hash",
          "description": "SHA-256 hash of the target file."
        }
      }
    },
    "certification": {
      "description": "Certification result.",
      "type": "object",
      "required": [
        "string",
        "type",
        "format"
      ],
      "properties": {
        "string": {
          "type": "string",
          "description": "The certification result itself."
        },
        "type": {
          "description": "Interpretation of `string`. The following values are supported:\n\n* `verdict`: Verdict about the targeted entry.",
          "enum": [
            "verdict"
          ]
        },
        "format": {
          "description": "Format of `string`. The following values are supported:\n\n* `confirmed | rejected`: Either \"confirmed\" or \"rejected\".",
          "enum": [
            "confirmed | rejected"
          ]
        }
      }
    }
  },
  "type": "array",
  "items": {
    "oneOf": [
      {
        "title": "Loop invariant",
        "description": "Loop invariants are important building blocks in software verification. Many verification approaches use loop invariants as lemmata to construct proofs of correctness.\n\nA _loop_ invariant should hold at various locations:\n1. before the loop,\n2. in the beginning of the loop body,\n3. at the end of the loop body,\n4. after the loop.",
        "type": "object",
        "required": [
          "entry_type",
          "metadata",
          "location",
          "loop_invariant"
        ],
        "properties": {
          "entry_type": {
            "const": "loop_invariant"
          },
          "metadata": {
            "$ref": "#/$defs/metadata"
          },
          "location": {
            "$ref": "#/$defs/location",
            "description": "Location in the source code where the loop invariant holds.\n\nAs the loop invariant has stronger semantics than a single location invariant, it does not correspond to an assertion at a single location. Therefore, this location should be such that a validator is able to associate it with a particular loop, for example, by placing the loop invariant immediately before the loop."
          },
          "loop_invariant": {
            "$ref": "#/$defs/invariant",
            "description": "The loop invariant description."
          }
        },
        "examples": [
          {
            "entry_type": "loop_invariant",
            "metadata": {
              "format_version": 0.1,
              "uuid": "91023a0f-9f45-4385-88c4-1152ade45537",
              "creation_time": "2021-05-05T13:18:43.000Z",
              "producer": {
                "name": "CPAchecker",
                "version": "2.0.1-svn",
                "configuration": "svcomp21--04-kInduction"
              },
              "task": {
                "input_files": [
                  "multivar_1-1.c"
                ],
                "input_file_hashes": {
                  "multivar_1-1.c": "511f45a8d763ef520f6d92e4135c8572805994a66531c6216b17157d0dde2f9c"
                },
                "specification": "CHECK( init(main()), LTL(G ! call(reach_error())) )",
                "data_model": "ILP32",
                "language": "C"
              }
            },
            "location": {
              "file_name": "multivar_1-1.c",
              "file_hash": "511f45a8d763ef520f6d92e4135c8572805994a66531c6216b17157d0dde2f9c",
              "line": 22,
              "column": 0,
              "function": "main"
            },
            "loop_invariant": {
              "string": "(x >= 1024U) && (x <= 4294967295U) && (y == x)",
              "type": "assertion",
              "format": "C"
            }
          }
        ]
      },
      {
        "title": "Location invariant",
        "description": "Invariant at a program location, which does not necessarily correspond to a loop.",
        "type": "object",
        "required": [
          "entry_type",
          "metadata",
          "location",
          "location_invariant"
        ],
        "properties": {
          "entry_type": {
            "const": "location_invariant"
          },
          "metadata": {
            "$ref": "#/$defs/metadata"
          },
          "location": {
            "$ref": "#/$defs/location",
            "description": "Location in the source code where the invariant holds."
          },
          "location_invariant": {
            "$ref": "#/$defs/invariant",
            "description": "The invariant description."
          }
        },
        "examples": [
          {
            "entry_type": "location_invariant",
            "metadata": {
              "format_version": 0.1,
              "uuid": "92c380d6-00a1-4e97-8c63-0f246206c6ab",
              "creation_time": "2022-05-16T11:56:13.480Z",
              "producer": {
                "name": "A2Y",
                "version": "1"
              },
              "task": {
                "input_files": [
                  "c/loops/trex04.c"
                ],
                "input_file_hashes": {
                  "c/loops/trex04.c": "f70ffe9cd45c37f44e9e780e31340fab45b6a2fb7f7ef23a2d90faf4241229d6"
                },
                "specification": "CHECK( init(main()), LTL(G ! call(reach_error())) )",
                "data_model": "ILP32",
                "language": "C"
              }
            },
            "location": {
              "file_name": "c/loops/trex04.c",
              "file_hash": "f70ffe9cd45c37f44e9e780e31340fab45b6a2fb7f7ef23a2d90faf4241229d6",
              "line": 47,
              "column": 0,
              "function": "main"
            },
            "location_invariant": {
              "string": "x <= 0",
              "type": "assertion",
              "format": "C"
            }
          }
        ]
      },
      {
        "title": "Invariant certificate",
        "description": "Invariant certificates document validation attempts of various invariants, for example by trying to use the target loop invariant in a proof of correctness.\n\nCertificates document correctness and trustworthiness of invariants.",
        "type": "object",
        "required": [
          "entry_type",
          "metadata",
          "target",
          "certification"
        ],
        "properties": {
          "entry_type": {
            "const": "invariant_certificate"
          },
          "metadata": {
            "$ref": "#/$defs/metadata-certificate"
          },
          "target": {
            "$ref": "#/$defs/target",
            "description": "Target entry of some invariant type which is being certified."
          },
          "certification": {
            "$ref": "#/$defs/certification",
            "description": "The invariant certification result description."
          }
        },
        "examples": [
          {
            "entry_type": "invariant_certificate",
            "metadata": {
              "format_version": 0.1,
              "uuid": "954affa9-32e4-4b35-85ae-888da3a6a53b",
              "creation_time": "2021-05-05T13:18:43.000Z",
              "producer": {
                "name": "CPAchecker",
                "version": "2.0.1-svn",
                "configuration": "svcomp21--04-kInduction"
              }
            },
            "target": {
              "uuid": "91023a0f-9f45-4385-88c4-1152ade45537",
              "type": "loop-invariant",
              "file_hash": "511f45a8d763ef520f6d92e4135c8572805994a66531c6216b17157d0dde2f9c"
            },
            "certification": {
              "string": "confirmed",
              "type": "verdict",
              "format": "confirmed | rejected"
            }
          }
        ]
      },
      {
        "title": "Ghost variable declaration",
        "description": "Declares and initializes a ghost variable used in this witness. Ghost variables can be updated at specific points during the execution of the program, and may be referred to in location invariants and other witness entries, unless otherwise specified.",
        "type": "object",
        "required": [
          "entry_type",
          "metadata",
          "variable",
          "scope",
          "type",
          "initial"
        ],
        "properties": {
          "entry_type": {
            "const": "ghost_variable"
          },
          "metadata": {
            "$ref": "#/$defs/metadata"
          },
          "variable": {
            "$ref": "#/$defs/variable-identifier",
            "description": "A valid identifier used as name of the ghost variable. This identifier must be unique across the witness, and must not be used in the program."
          },
          "scope": {
            "enum": [
              "global"
            ],
            "description": "The scope of the ghost variable. For now, only global ghost variables are supported."
          },
          "type": {
            "type": "string",
            "description": "A C type, either built-in or declared in the program."
          },
          "initial": {
            "type": "string",
            "description": "A syntactically well-formed C expression without side-effects, and without calls to functions defined in the program. The only variables allowed in this expression are the global variables of the program. The expression is evaluated after global variables declared in the program are initialized; this evaluation must not lead to undefined behaviour."
          }
        },
        "examples": [
          {
            "entry_type": "ghost_variable",
            "metadata": {
              "format_version": 0.1,
              "uuid": "ee9cc5a7-2f8d-43c2-bcac-cde6f5b6d048",
              "creation_time": "2023-07-07T17:17:17.000Z",
              "producer": {
                "name": "Ultimate GemCutter",
                "version": "0.2.3-dev"
              },
              "task": {
                "input_files": [
                  "ghosts.c"
                ],
                "input_file_hashes": {
                  "ghosts.c": "2b56726d10d5a52c002223c251596e534cc0842633245a85ece0f2a6f854bd14"
                },
                "specification": "CHECK( init(main()), LTL(G ! call(reach_error())) )",
                "data_model": "ILP32",
                "language": "C"
              }
            },
            "variable": "g",
            "scope": "global",
            "type": "int",
            "initial": "0"
          }
        ]
      },
      {
        "title": "Ghost variable update",
        "description": "Updates the value of a ghost variable used in this witness. Ghost variables can be updated at specific points during the execution of the program, and may be referred to in location invariants and other witness entries, unless otherwise specified.",
        "type": "object",
        "required": [
          "entry_type",
          "metadata",
          "variable",
          "expression",
          "location"
        ],
        "properties": {
          "entry_type": {
            "const": "ghost_update"
          },
          "metadata": {
            "$ref": "#/$defs/metadata"
          },
          "variable": {
            "$ref": "#/$defs/variable-identifier",
            "description": "The identifier for the updated ghost variable. This variable must be declared in an entry of type ghost_variable in the witness."
          },
          "expression": {
            "type": "string",
            "description": "A syntactically well-formed C expression without side-effects, and without calls to functions defined in the program. The expression may use any program variables that are in scope at the specified location (see below), as well as any ghost variables declared in the witness (if they are in scope). Evaluation of the expression upon reaching the location must not lead to undefined behaviour. We assume however that the evaluation is performed atomically, i.e., by assumption the evaluation does not cause a data race.",
            "TODO": "Isn't a data race on a global program variable between an atomic read (in this expression) and a non-atomic write (in another thread in the program) possible?"
          },
          "location": {
            "$ref": "#/$defs/location",
            "description": "The location at which the ghost variable is updated. Specifically, the ghost update is executed when control exits the specified location. The ghost update is performed atomically together with the action exiting the location."
          },
          "branching": {
            "$ref": "#/$defs/branching-constraint",
            "description": "Optionally, the ghost update may be performed only for certain actions leaving a location rather than for all actions; for instance, only if a branch evaluates to true. The specification of the selected actions should be analogous to branching waypoints in violation witnesses."
          }
        },
        "examples": [
          {
            "entry_type": "ghost_update",
            "metadata": {
              "format_version": 0.1,
              "uuid": "dc7c0b90-d998-4920-b9a0-af8a9f058875",
              "creation_time": "2023-07-07T17:17:17.000Z",
              "producer": {
                "name": "Ultimate GemCutter",
                "version": "0.2.3-dev"
              },
              "task": {
                "input_files": [
                  "ghosts.c"
                ],
                "input_file_hashes": {
                  "ghosts.c": "2b56726d10d5a52c002223c251596e534cc0842633245a85ece0f2a6f854bd14"
                },
                "specification": "CHECK( init(main()), LTL(G ! call(reach_error())) )",
                "data_model": "ILP32",
                "language": "C"
              }
            },
            "variable": "g",
            "expression": "5",
            "location": {
              "file_name": "ghosts.c",
              "file_hash": "511f45a8d763ef520f6d92e4135c8572805994a66531c6216b17157d0dde2f9c",
              "line": 22,
              "column": 0,
              "function": "main"
            },
            "branching": {
              "constraint": {
                "value": true
              }
            }
          }
        ]
      }
    ]
  }
}