More proofreading

Author: nichtich

README.md

@@ -75,6 +75,10 @@ Locators can contain **nested errors** within the addressed part of a document:
 }
 ~~~
 
+## Building the specification document
+
+Requires `quarto`.
+
 ## Implementations
 
 See [directory `examples`](examples) for an example implementation of an XML validator supporting this error format.

_quarto.yml

@@ -14,14 +14,26 @@ repo-url: https://github.com/gbv/validation-error-format
 resources:
   - schema.json
 
+callout-appearance: simple
+number-sections: true
+number-depth: 2
+notebook-links: false
+crossref:
+  lst-prefix: "Example"
+  lst-title: "Example"
+lst-cap-location: bottom
+
 format:
   html:
     highlight-style: kate
-    notebook-links: false
-    number-sections: true
-    number-depth: 2
     css: style.css
-    crossref:
-      lst-prefix: "Example"
-      lst-title: "Example"
-    lst-cap-location: bottom
+#  pdf:
+#    toc: false
+#    code-tools:
+#      source: false
+#    sansfont: Linux Biolinum O
+#    mainfont: Linux Biolinum O
+#    keeptex: true
+
+execute:
+  freeze: true

index.qmd

@@ -8,17 +8,19 @@ authors:
   affiliations:
    - name: Verbundzentrale des GBV (VZG)
 abstract: |
- This document specifies a data format to report validation errors of digital objects.
+ This document specifies a data format to report validation errors of digital objects with error positions independent from specifid document models.
 ---
 
 # Introduction
 
+> _All data is wrong, but some data is wrong on multiple levels._
+
 Data validation is a crucial part of management of data quality and interoperability. Validation is applied in many ways and contexts, for instance input forms and editors with visual feedback or schema languages with formal error reports. The diversity of use cases imply a variety of error results. Existing standards for error reporting such as such as [JUnit XML](https://github.com/testmoapp/junitxml) and [Test Anything Protocol](https://testanything.org/) have narrow use cases in software development.
 
 The specification of **Data Validation Error Format** has two goals:
 
-- unify how validation errors are reported by different validators
-- address positions of errors in validated documents, independent from document formats
+- unify how validation errors are reported by different applications
+- reference positions of errors in validated documents, independent from document models
 
 Last but not least the format should help to better separate validation and presentation of validation results, so both can be solved by different applications.
 
@@ -49,9 +51,9 @@ Every document conforms to a **document model**. For instance JSON documents con
 Eventually all documents are given as digital objects, encoded as sequence of bytes. Encodings using a sequence of characters are also called textual data formats, in contrast to binary data formats.
 :::
 
-An [error position](#sec-positions) is given in form of one or more **locators**, each having a [**dimension**](#sec-dimensions) and an **address**. Each dimension refers to a **locator format** for a set of document models. For instance [JSON Pointer] refers to JSON, character and line numbers refer to character strings with defined line breaks, and offsets refer to sequences of elements (@fig-encodings-and-locators). Other examples of locator formats include [XPath] for XML, and row/column for tabular data.
+An [error position](#positions) is given in form of one or more **locators**, each having a [**dimension**](#dimensions) and an **address**. Each dimension refers to a **locator format** for a set of document models. For instance [JSON Pointer] refers to JSON, character and line numbers refer to character strings with defined line breaks, and offsets refer to sequences of elements (@fig-encodings-and-locators). Other examples of locator formats include [XPath] for XML, and row/column for [tabular data](#tabular-document-models).
 
-Locators can also contain **nested errors** to address a more specific position within another position and to support error positions in nested documents such as archive files.
+Locators can also contain **nested errors** to reference a more specific position within another position and to support error positions in nested documents such as archive files.
 
 ::: {#fig-encodings-and-locators}
 
@@ -153,70 +155,90 @@ A similar document could be invalid on byte level. The following table illustrat
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 ([RFC 2119] and [RFC 8174]) when, and only when, they appear in all capitals, as shown here.
 
-Only section @sec-errors to @sec-dimensions, excluding examples and notes, and the [list of normative references](#normative-references) are normative parts of this specification.
+Only section [2](#errors) to [4](#dimensions), excluding examples and notes, and the [list of normative references](#normative-references) are normative parts of this specification.
 
+<!--
 Specific support of Data Validation Error Format by an application depends on:
 
-1. the set of supported [**dimensions**](#sec-dimensions), and
-2. whether [**positions**](#positions) are supported in both full ([**locators**](#locators)) and condense form ([**locator maps**](#locator-map)), or only the latter.
+1. the set of supported [**dimensions**](#dimensions), and
+2. whether [**positions**](#positions) are supported only in condense form ([**locator maps**](#locator-map)), or also in full form (array of [**locators**](#locators)) 
 
 Both MUST be documented by applications.
+-->
 
-# Errors {#sec-errors}
+# Errors
 
-An **Error** is a JSON object with: 
+An **Error** is a JSON object with the following constraints: 
 
-- optional (but RECOMMENDED) field `message` with an **error message**, being a non-empty string.
-  Applications MAY use a default value for error messages.
+- an error SHOULD have a field `message` with an **error message**, being a non-empty string.
+  Applications MAY use a default value for error messages. Language and localization of error
+  messages is out of the scope of this specification.
 
-- optional field `types` with an array of **error types**, each being a non-empty string.
-  Error types can be used for grouping errors or to reference a cause or constraint being violated
-  with the error. Error types SHOULD be either URIs ([RFC 3986]) or local identifiers
-  with same syntax as the name of a [dimension](#dimensions) or 
+- an error MAY have field `types` with an array of **error types**, each being a non-empty string.
+  Error types can be used for grouping errors and to reference a cause or constraint being violated
+  by the error. Error types SHOULD be URIs ([RFC 3986]) local identifiers
+  with same syntax as the name of a [dimension](#dimensions).
 
-- optional field `level` with an **error level**, being one of the strings `error`, `warning`, or `info`.
-  Application MUST use default value `error` if this field is not given.
+- an error MAY have field `level` with an **error level**, being one of the strings `error`, `warning`, or `info`. Application MUST use default value `error` if this field is not given.
 
-- optional field `position` with a [**position**](#positions).
+- an error MAY have field `position` with a [**position**](#positions).
   Applications MUST NOT differentiate between no position and an empty position (an empty array or an empty JSON object).
 
+Applications MUST use individual errors for individual positions of the kind of observation represented by the error. For instance a malformed character ocurring two times in a document results in two errors.
+
 ::: {.callout-note}
-Language and localization of error messages is out of the scope of this specification.
+By this definition the error `{}` is allowed and equivalent to `{"level":"error"}`.
 :::
 
 # Positions
 
-An error can have a **position**. A position is given
+The position of an error is given
 
-- either in **full form** as JSON array of [**locators**](#locators),
+- either in **condense form** with a [**locator map**](#locator-maps),
 
-- or in **condense form** with a [**locator map**](#locator-maps).
+- or in **full form** as JSON array of [**locators**](#locators).
 
-Every locator map can be transformed to an equivalent array of locators. The reverse transformation is only possible if there is at most one locator per dimension and no locator has nested errors.
+Every locator map can be transformed to an equivalent array of locators. The reverse transformation is only possible if no locator has [nested errors](#locators) and there is not more then one locator per dimension.
 
-::: {.callout-note}
-Locators of the same positions should refer to roughly the "same" part of a document or at least have a common intersection. This requirement is difficult to formalize because locators refer to different document models, so it is no normative part of this specification.
-:::
+A position with multiple locator of the same dimension does nor imply multiple errors but it references multiple elements involved in the same error (for instance a mismatch between two elements). Locators of different dimensions in the same position SHOULD refer to the the same elements or have a common intersection.
 
 [locator format]: #locator-formats
 [locator map]:: #locator-maps
 
-## Locators
+## Locator maps
+
+A **locator map** is a JSON object that maps names of [**dimensions**](#dimensions) to [**addresses**](#dimensions).
+
+```{#lst-locator-map .json lst-cap="A simple locator map indicating the position line 7, character 42"}
+{ "line": "7", "char": "42" }
+```
 
-A **Locator** is a JSON object with
+A locator map can be transformed to an equivalent array of [locators](#locators) with key and value of the JSON object entries mapped to field `dimension` and `address` of each locator.
 
-- mandatory field `dimension` with the name of a [**dimension**](#dimensions)
+```{#lst-locator-map .json lst-cap="Equivalent array of locators"}
+[
+  { "dimension": "line", "address": "7" },
+  { "dimension": "char", "address": "42" }
+]
+```
 
-- mandatory field `address` with the **address**, being a string conforming to the **locator format** identified by the name of the **dimension**.
+Applications MAY restrict their support of Data Validation Error Format to positions in condense form being  locator maps.
 
-- optional field `errors` with an array of nested [**errors**](#sec-errors) within the located part of a document.
+## Locators
 
+A locator references an element of a document. A **Locator** is a JSON object with the following constraints:
+
+- the locator MUST have a field `dimension` with the name of a [**dimension**](#dimensions). Some dimensions imply a document model on elements referenced by locators of this dimension.
+
+- the locator MUST have a field `address` with the **address**, being a string conforming to the **locator format** identified by the name of the **dimension**.
+
+- the locator MAY have a field `errors` with an array of [**errors**](#errors) within the located element (**nested errors**).
 
 ```{#lst-locator .json lst-cap="A simple locator"}
 { "dimension": "line", "address": "7" }
 ```
 
-Nested errors allow to reference locations within nested documents (@lst-nested-example and @lst-nested-example-2):
+Nested errors allow to reference locations within elements of a document. Positions of nested errors MUST be relative to the element referenced by their parent locator (@lst-nested-example and @lst-nested-example-2):
 
 ```{#lst-nested-example .json lst-cap="An error in line 2 of file `example.txt` in archive `archive.zip`"}
 {
@@ -256,36 +278,17 @@ Nested errors allow to reference locations within nested documents (@lst-nested-
 }
 ```
 
-## Locator maps
-
-A **locator map** is a JSON object that maps names of [**dimensions**](#sec-dimensions) to [**addresses**](#sec-dimensions).
-
-```{#lst-locator-map .json lst-cap="A simple locator map indicating the position line 7, character 42"}
-{ "line": "7", "char": "42" }
-```
-
-A locator map can be transformed to an equivalent array of [locators](#locators) with key and value of the JSON object entries mapped to field `dimension` and `address` of each locator. An array of locators can be reduced to a locator map by dropping all nested errors and selecting only the first locator of each locator format.
-
-```{#lst-locator-map .json lst-cap="Equivalent array of locators"}
-[
-  { "dimension": "line", "address": "7" },
-  { "dimension": "char", "address": "42" }
-]
-```
-
-Applications MAY restrict their support of Data Validation Error Format to positions with locator maps. In this case nested errors and positions with multiple locators per dimension are not supported.
-
-# Dimensions {#sec-dimensions}
+# Dimensions
 
-A **dimension** is a defined method to address elements of a document. Each dimension has:
+A **dimension** is a defined method to reference elements of a document. Each dimension has:
 
 - a unique **name**, being a string that start with lowercase letter `a` to `z`, optionally followed by a sequence of lowercase letters and digits `0` to `9`.
 
-- a **locator format**, being a formal language of Unicode strings to encode references to parts of a document. The sets of strings of the language are called **addresses**.
+- a **locator format**, being a formal language of Unicode strings to encode references to elements of a document. The sets of strings of the language are called **addresses**.
 
 - a **document model** matching the **locator format**.
 
-Some dimensions imply a document model on addressed elements. For instance a [line number] addresses a character string and a [JSON Pointer] addresses a JSON value.
+Some dimensions imply a document model on referenced elements (element model). For instance a [line number] references a character string and a [JSON Pointer] references a JSON value.
 
 Applications SHOULD support the following dimensions. The [appendix](#sec-additional-dimensions) contains a non-normative note on additional dimensions not fully specified yet.
 
@@ -303,10 +306,10 @@ name            | locator format          | document model
 `jsonpointer`   | [JSON Pointer]          | JSON value                              | JSON value
 `xpath`         | [XML Element Locator]   | XML or compatible hierarchies           | XML
 
-The **identifier** locator format with name `id` and locator values being arbitrary Unicode strings subsumes every other locator format because locators of same value refer to the same element. It can be used for any kind of formalized reference to elements of a document, but its main use case are record identifiers, unique names and similar identifier systems.
+The **identifier** locator format with name `id` and locator values being arbitrary Unicode strings subsumes every other locator format because locators of same value refererence the same element. It can be used for any kind of formalized reference to elements of a document, but its main use case are record identifiers, unique names and similar identifier systems.
 
 :::{.callout-note}
-Dimensions are a subset of query languages. A dimension value locates to *one* element from a document. A query language (e.g. JSONPath, full XPath...) can locate a set of elements.
+Dimensions are a subset of query languages. A dimension value refererences one element from a document. A query language (e.g. JSONPath, full XPath...) can locate a set of elements.
 :::
 
 ## Sequential document models
@@ -375,7 +378,7 @@ DIGIT          = %x30-39
 ```
 
 :::{.callout-note}
-Tabular selection locator is a proper subset of [RFC 7111] URI Fragment Identifier.
+Tabular selection locator is a proper subset of [RFC 7111] URI Fragment Identifier, excluding [multi-selections].
 :::
 
 ## Hierarchical document models
@@ -401,10 +404,10 @@ Position          = %31-%39 *DIGIT
 DIGIT             = %x30-39  ; 0...9
 ```
 
-Applications MAY append the string `[1]` to an XML Element Locator if it does not end with a `Position` to ensure that a single element is referenced.
+Applications MUST NOT use one XML Element Locators to reference multiple XML elements. For this reason applications MAY always append the string `[1]` to an XML Element Locator if it does not end with a `Position`.
 
 ::: {.callout-note}
-XML Element Locator is a proper subset of (X)Path Expressions from [XPath] specifications.
+XML Element Locator is a proper subset of (X)Path Expressions from [XPath] specifications, limited to reference individual XML elements or attributes.
 :::
 
 [QName]: https://www.w3.org/TR/REC-xml-names/#NT-QName

style.css

@@ -9,7 +9,12 @@ figcaption {
 .listing > figure > figcaption {
   text-align: left;
 }
-.callout.callout-style-default .callout-body, 
-.callout.callout-style-default > div.callout-header {
+.callout.callout-style-simple .callout-body {
   font-size: 1rem;
 }
+a {
+  text-decoration: none;
+}
+a:hover {
+  text-decoration: underline;
+}