Extensible Validation Report Language (XVRL)

XVRL Vocabulary XVRL elements are in the namespace http://www.xproc.org/ns/xvrl. XVRL documents may contain elements in other namespaces at certain locations. The XVRL elements and attributes and their semantics are given in the following lists. More details about the XVRL grammar are encoded in the Relax NG Compact Syntax version of the XVRL schema, which is also normative.

Document Structure detection element A single finding, typically with an associated error code and/or message(s). A report element primarily contains detection elements. See for details. digest element A report may contain a digest element in order to provide a summary of the detection elements. For the distinct severity levels, counts of the detection elements for a given level may be specified on digest, for example in an @error-count attribute. In addition, the @worst attribute may give the highest severity level that occurs in the detection elements that are contained by the digest’s parent element. A digest element may occur in addition to or instead of detection elements. If no detection element is included, a digest element must be included. All information in digest is understood to be aggregated at some point from the actual detection elements. It is the responsibility of an XVRL creating/processing application to keep them up to date or to remove them when the underlying detection information is changed. A digest may be inserted either before or after the detection elements. metadata element Information about the time of validation, the validator used, the document(s) under test, etc. See for details. A single metadata element need not contain all relevant metadata. Metadata infomation will be inherited from surrounding reports/metadata elements, that is, if a given metadata does not provide validator information but the parent reports/metadata does, the parent’s metadata/validator will also pertain to the current metadata element’s siblings and their descendants, unless overridden further down. report element The result of a single validation method, typically using a single schema, typically applied to a single document (also referred to as the source document). The individual errors (or other findings) are included as detection elements. Naming things… Previously, what is called “detection” here was called “report”, while a collection of detections was called “validation-report”. Now this collection ist called “report”, while a collection of (new-terminology) reports is now called “reports” (previously: “validation-reports”). I changed the names because I didn’t think that both an individual finding and a collection of individual findings should both be called a “report”, with the prefix “validation-” discerning between both. Since the individual finding is also the result of a validation, there is no reason it couldn’t have been called “validation-report” in the first place. It took quite some time to come up with a term for the individual findings. Candidates were: “finding”, “observation”, “detection”, “incidence”, and “incident”. I’m willing to rename it to something that seems more fitting. reports element A collection of report elements. It may contain the same metadata information as a single report in order to denote common information, for example if all validations have been applied to the same document or if all validations use the same schema or validation engine. reports elements may nest in order to group report elements with common sets of metadata.

Detection As described in , detection is the main container for individual validation findings. It contains optional severity and code attributes, and the following elements in arbitrary order: category element(s) In order to filter or group messages for a formatted report, individual detections may be categorized according to arbitrary category systems, using the repeatable category element. Its optional attribute vocabulary can hold a string that designates the category system. There are no pre-defined values to choose from. Categorization that applies to all detections in a report can be included in the report’s metadata. code attribute An error code. The term “error code” is used in a colloquial sense here. It need not relate to an error, but to any kind of message that has a distinctive identifying string. context element The purpose of this element is to present a piece of content that surrounds the element that the detection pertains to. It contains an optional location element, followed by (optional) arbitrary text or non-XVRL element content. location element Within a single detection element, the location in the source document that the validation error, warning, etc. pertains to is given by the location element’s attributes. If not present, href is taken from the closest ancestor’s metadata/document/@href attribute. If there are multiple document/@href attributes in the closest ancestor’s metadata, the href attribute should not be omitted on location, or at least a disambiguating relative URI should be given in the location/@href attribute. The attribute xpath contains an XPath expression that gives the location within the document. The in-scope value of the attribute xpath-default-namespace that is permitted on any element may give a namespace for the element names in this XPath expression. Apart from that, the Q{namespace-uri}local-name syntax should be used, but in-scope namespace prefixes or XPath predicates like [namespace-uri() = 'uri'] may also be used. The attributes line and column may also be used to point at lines and columns in a textual representation of the source document. The attribute octet-position may be used to give the byte position (1-offset) of the error. This may be useful for binary documents. In order to support JSON document validations, the attributes jsonpath and jsonpointer may be used. Giving multiple alternative pointers is not forbidden. However, it is beyond the scope of this specification to define mechanisms to enforce or check consistency between the attribute values. It is evident that jsonpointer or jsonpath are meaningless in the context of XML documents. Other attributes are permitted if they are in a non-XVRL namespace. message element An error message that pertains to a detection. There may be multiple message elements in a single detection element, typically to convey localized versions of essentially the same message. A message may contain arbitrary markup in non-XVRL namespaces. Messages are typically generated for consumption by humans. Whenever the term “error message” is used in a colloquial sense (that is, not highlighted as the severity level “error” or as the XVRL element “message”) throughout this specification, a detection element with any @severity level, not necessarily “error”, and any number of localized messages is implied. Likewise, the term “error code” does not imply the severity level “error”. provenance element In multi-step conversion pipelines it is sometimes required to save a common origin location that a portion of the validated document is derived from. This may be necessary in order to patch back error messages of later conversion stages into the source document. The optional provenance element within a detection conveys exactly this information, in a contained location element that points to the provenance location in the original source document. A provenance element may contain multiple location elements; it is up to processing applications to discern between different roles that they may have. Although it is possible to omit the @href attribute in the contained location elements, this URI is not inherited from a containing element’s metadata/document/@href attribute. severity attribute The severity attribute is permitted on a detection element. XVRL establishes a finite set of error levels that correspond to the impact of a detected issue. Each detection element may have a severity level, from highest (worst impact) to lowest, of “fatal-error”, “error”, “warning”, or “info”. In addition, the severity attribute may have the value “unspecified” which is equivalent to omitting the attribute. Which severity level is attached to a given error code depends on, among other things, the audience that the validation report is prepared for. For Schematron’s SVRL output, the values of @role will typically translate to XVRL @severity attributes, but this mapping may be configured, see below. summary element(s) An abstract of a report, a reports collection, or an individual detection. This element is repeatable, for example, in order to support multiple natural languages. In the context of detection, it can serve as an abridged version of a full message that contains lengthy lists and the like. supplemental element(s) This repeatable element may contain arbitrary textual or non-XVRL element content. It may appear in metadata and in detection. Its role attribute may be used to further classify the purpose of its content. Like any other XVRL element, it may be localized using the xml:lang attribute. Purposes can be, but are not limited to, conveying the SVRL source that the XVRL report was created from, or a disclaimer, a confidentiality statement, or introductory content that should be included in a rendered report.

Metadata All elements in this section are optional within metadata. The order in which they appear is arbitrary. Some are repeatable. creator element Information about the tool that created the source document. There are the optional attributes @name, @version, and the optional element invocation. The invocation element is meant to hold a command line that contains the invocation of the program that was responsible for generating the source document. This information can be useful for later diagnosing dependencies between errors and command line options. category element(s) See document element(s) The URI of a source document may be specified in the href attribute. In addition or instead, the document may be given as the element content. See also about inheritance of href. schema element(s) The URI of a schema document may be specified in the href attribute. In addition or instead, the document may be given as the element content. For schema languages that have a distinct XML namespace, the namespace of the schema may be given in the attribute schematypens. Some schema languages have a distinct content type. This can be conveyed in the attribute content-type. In addition or alternatively to the aforementioned attributes, the schema language may be specified by a distinct token in the attribute language. Tokens for well-known schema languages are listed in . Schema languages that do not appear in should be referred to by a language token that is prefixed with x- and that contains a reasonably recognizable identifier for the given schema language. The version of the schema language may be given in the attribute version. summary element(s) See . supplemental element(s) See . timestamp element >The content needs to be an xsd:dateTime value, for example “2017-12-04T12:21:37.381+01:00”. title element(s) The title of a report, a reports collection, or an individual detection. This element is repeatable, for example, in order to support multiple natural languages. validator element Information about the validation program that generated the report(s) or the underlying messages (if XVRL was not generated natively by the program). There are optional attributes @name and @version, both are arbitrary strings. Arbitrary text or element (in a non-XVRL namespace) content may be contained, for example to describe a configuration or to include an actual configuration file.