Schema for the XML formatΒΆ
For reference, here’s the RELAX-NG schema for the XML serialization format:
<?xml version="1.0" encoding="UTF-8"?> <!-- Copyright 2013 David Malcolm <dmalcolm@redhat.com> Copyright 2013 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA --> <grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <start> <!-- Results from the invocation of an analysis tool --> <element name="analysis"> <ref name="metadata-element"/> <element name="results"> <zeroOrMore> <choice> <ref name="issue-element"/> <ref name="failure-element"/> <ref name="info-element"/> </choice> </zeroOrMore> </element> <optional> <ref name="custom-fields-element"/> </optional> </element> </start> <define name="metadata-element"> <element name="metadata"> <element name="generator"> <attribute name="name"/> <optional> <attribute name="version"/> </optional> </element> <!-- "sut" = "Software Under Test" --> <optional> <element name="sut"> <choice> <element name="source-rpm"> <attribute name="name"/> <attribute name="version"/> <attribute name="release"/> <attribute name="build-arch"/> </element> <!-- Debian SUT entries --> <element name="debian-source"> <!-- Report for a Debian source package --> <attribute name="name"/> <attribute name="version"/> <optional> <!-- This entry is optional because Debian packages may be `native' (e.g. no local version, since local and upstream are the same). --> <attribute name="release"/> </optional> <!-- No build arch; source is arch indep. --> </element> <element name="debian-binary"> <!-- Report for a Debian .deb package --> <attribute name="name"/> <attribute name="version"/> <optional> <attribute name="release"/> </optional> <attribute name="build-arch"/> <!-- Valid entries include `amd64', `kfreebsd-amd64', `armhf', `hurd-i386', among others for Debian. --> </element> <!-- What other options should we have? --> </choice> </element> </optional> <optional> <ref name="file-element"/> </optional> <optional> <element name="stats"> <!-- actual time taken to run the analysis, in seconds --> <attribute name="wall-clock-time"> <data type="float"/> </attribute> </element> </optional> </element> </define> <!-- Definitions of the various kinds of result follow: <issue> <failure> <info> --> <!-- A report about a possible problem --> <define name="issue-element"> <element name="issue"> <optional> <!-- The Common Weakness Enumeration ID (see http://cwe.mitre.org/index.html ) e.g. "131" representing CWE-131 aka "Incorrect Calculation of Buffer Size" http://cwe.mitre.org/data/definitions/131.html --> <attribute name="cwe"> <data type="integer"/> </attribute> </optional> <optional> <!-- Each static analysis tool potentially has multiple tests, with its own IDs for its own tests. Capture those that do here, as free-form strings: --> <attribute name="test-id"/> </optional> <optional> <!-- Each static analysis tool potentially can report a "severity", which may be of use for filtering. The precise strings are likely to vary from tool to tool. To avoid data-transfer issues, support storing it as an optional freeform string here. See: http://lists.fedoraproject.org/pipermail/firehose-devel/2013-February/000001.html --> <attribute name="severity"/> </optional> <!-- A message summarizing the problem --> <ref name="message-element"/> <!-- Additional descriptive details This might support some simple markup at some point (as might <message>) --> <optional> <element name="notes"><text/></element> </optional> <!-- Where is the problem? --> <ref name="location-element"/> <optional> <!-- How can the problem occur? --> <element name="trace"> <oneOrMore> <element name="state"> <ref name="location-element"/> <optional> <element name="notes"><text/></element> </optional> <!-- optionally we can supply key-value pairs --> <zeroOrMore> <element name="annotation"> <element name="key"><text/></element> <element name="value"><text/></element> </element> </zeroOrMore> </element> </oneOrMore> </element> </optional> <!-- A given tool/testid may have additional key/value pairs that it may be useful to capture: --> <optional> <ref name="custom-fields-element"/> </optional> </element> </define> <!-- A report about a failed analysis. If any of these are present then we don't have full coverage. For some analyzers this is an all-or-nothing affair: we either get issues reported, or a failure happens (e.g. a segfault of the analysis tool). Other analyzers may be more fine-grained: able to report some issues, but choke on some subset of the code under analysis. For example cpychecker runs once per function, and any unhandled Python exceptions only affect one function. --> <define name="failure-element"> <element name="failure"> <optional> <!-- Each static analysis tool potentially can identify types of way that it can fail. Capture those that do here, as (optional) free-form strings: --> <attribute name="failure-id"/> </optional> <optional> <!-- Some analysis tools may be able to annotate a failure report by providing the location *within the software-under-test* that broke them. For example, gcc-python-plugin has a gcc.set_location() method which can be used by a code analysis script to record what location is being analyzed, so that if unhandled Python exception happens, it is reported at that location. This is invaluable when debugging analysis failures. --> <ref name="location-element"/> </optional> <optional> <!-- summary of the failure --> <ref name="message-element"/> </optional> <!-- Every type of failure seems to have its own kinds of data that are worth capturing: * stdout/stderr/returncode for a failed subprocess * traceback for an unhandled Python exception * verbose extra information about a cppcheck failure etc. Hence allow a <failure> to optionally contain extra key/value pairs, based on the failure-id. --> <optional> <ref name="custom-fields-element"/> </optional> </element> </define> <!-- Sometimes you may want a tool to report other kinds of information about the software-under-test that isn't a problem as such, e.g. code metrics, copyright/license info, cross-referencing information etc, hence the <info> element: --> <define name="info-element"> <element name="info"> <optional> <!-- An optional free-form string identifying the kind of information being reported: --> <attribute name="info-id"/> </optional> <optional> <ref name="location-element"/> </optional> <optional> <ref name="message-element"/> </optional> <optional> <ref name="custom-fields-element"/> </optional> </element> </define> <!-- ...end of result definitions. Various supporting elements follow: --> <!-- Summary text aimed at a developer. This is required for an <issue>, but is also can (optionally) be provided by a <failure> or <info> --> <define name="message-element"> <element name="message"><text/></element> </define> <define name="location-element"> <!-- A particular source code location --> <element name="location"> <ref name="file-element"/> <!-- Ideally, every analyzer would tell us in which function each problem was discovered, given that function names are less likely to change than line numbers. Unfortunately many don't - and we should patch these in each upstream analyzer as we go. Also, a problem can occur in global scope (e.g. lack of NULL termination in an array-initializer for a global, such as in this checker: http://gcc-python-plugin.readthedocs.org/en/latest/cpychecker.html#verification-of-pymethoddef-tables (although arguably there *is* a relevant function there: the location of the code that uses that data) --> <optional> <element name="function"> <attribute name="name"/> </element> </optional> <!-- We can refer to either a location, or a range of locations within the file: --> <choice> <ref name="point-element"/> <element name="range"> <!-- start of range: --> <ref name="point-element"/> <!-- end of range: --> <ref name="point-element"/> </element> </choice> </element> </define> <define name="file-element"> <element name="file"> <!-- What filename was given by the analyzer? This is typically the one supplied to it on the command line, which might be absolute or relative. Examples: - "foo.c" - "./src/foo.c" - "/home/david/libfoo-1.0/src/foo.c" --> <attribute name="given-path"/> <!-- Optionally, record the absolute path of the file, to help deal with collating results from a build that changes working directory (e.g. recursive make) --> <optional> <attribute name="absolute-path"/> </optional> <optional> <element name="hash"> <attribute name="alg"/> <attribute name="hexdigest"/> </element> </optional> </element> </define> <define name="point-element"> <element name="point"> <attribute name="line"/> <attribute name="column"/> </element> </define> <!-- A big escape-hatch in the schema: support for arbitrary, ordered key/value pairs for roundtripping data specific to a particular situation. e.g. debugging attributes for a particular failure --> <define name="custom-fields-element"> <element name="custom-fields"> <zeroOrMore> <choice> <element name="str-field"> <attribute name="name"/> <text/> </element> <element name="int-field"> <attribute name="name"/> <data type="integer"/> </element> </choice> </zeroOrMore> </element> </define> </grammar>