Constraint Format

1 Introduction

…

1.1 Overview

A Data Model is a set of documented elements from a specific data format
A Constraint Pattern is an abstract definition of a function that gets a set of parameters and a document as input and returns an analysis result report
A Constraint is a reference to a constraint pattern with all parameters set to specific values
A Constraint Template is a reference to a constraint with optional parameter values and a sentence where part of the sentence are mapped to parameters
An Analysis Result lists elements of a document together with references to constraints and whether their conditions have been met in the document

1.2 Conformance requirements

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.

2 Data Types

The format of data model, constraint pattern, constraint template, constraint, and analysis result are defined based on JSON. The specification refers to the following data types based on the basic JSON data types object with pairs of fields and values, array with members, string, number, boolean and null.

2.1 language tag

A language tag is a non-empty string that conforms to the syntax of RFC 5646 language tags limited to lowercase plain languages (grammar rule language of the specification).

2.2 name

A name is a string starting with a letter (a to z), optionally followed by more letters, digits (0 to 9), and minus (-).

2.3 URI

An URI is a syntactically correct IRI (RFC 3987).

3 Base Format

A base format is a name referencing a set of abstract documents with some internal structure.

Example 1 Base format xml references XML documents with a hierarchical structure (XML Elements, Attributes…) defined by XML Information Set.

See Appendix Base Formats for a preliminary list of base formats and their path languages

4 Pathes

A path language is a set of strings following a defined syntax and semantics to reference elements and/or subsets of documents of some base format.

A path is a string conforming to a path language.

Example 2 (Examples) Path language xpath follows XPath syntax and semantics to reference elements or subsets of XML documents (base format xml). For instance path //record/@id refers to every XML Attribute with name id of any XML Element with name record.

5 Data Model

A data Model is a JSON object with the following fields:

id - identifier of the model. SHOULD be an URI.
title - title of the model
format - a base format
language - a path language (set to a default value for each base format, e.g. xpath for xml)
elements - a set of elements, given as JSON object with fields being names and values being elements

An element is a JSON object with the following fields:

label - human-readable labels given as JSON object with fields being language tags and values being non-empty strings.
paths - a JSON array with a set of pathes
language - a path language, set to the value of language of the data model by default.

The elements of paths are equal alternatives. For instance XPath pathes ["//foo","//bar"] and ["//foo|//bar"] are equivalent because XPath expressions can be joined with |.

Data models can often be derived from schema files (XML Schema, JSON Schema, OWL Ontology, Avram Schema…) by extraction of elements and labels.

Example 3

{
  "id": "records-1.0",
  "title": "Record Format 1.0",
  "format": "xml",
  "elements": {
    "record": {
      "paths": ["//record"],
      "label": { "en": "Record", "de": "Datensatz" }
    },
    "id": {
      "paths": ["//@id"],
      "label": { "en": "identifier", "de": "ID" }
    }
  }
}

A data model for an XML format with XPath pathes.

6 Constraint

A Constraint is a JSON object with the following fields:

id (OPTIONAL) - identifier of the constraint. SHOULD be an URI.
pattern (REQUIRED) - identifier of a constraint pattern
format (REQUIRED) - a base format
model (OPTIONAL) - identifier of a data model. Value of format of constraint and data model MUST be identical.
parameters (REQUIRED) - a JSON object with fields being the parameter names of the constraint pattern and values matching to the parameter type.
… (OPTIONAL) metadata field such as keywords, created…

xample (minimal form for checking/execution/analysis):

Example 4

{
  "pattern": "MandatoryChild",
  "format": "xml",
  "parameters": {
     "parent": "//record",
     "child": "//@id"
  }
}

A constraint for the data model above.

7 Constraint Pattern

An Constraint Pattern is a JSON object with:

id (OPTIONAL) - identifier of the pattern
description - human-readble description (English) TODO: multi-lingual?
formats (OPTIONAL) - list of base formats this pattern can be applied to
parameters (REQUIRED) - parameters of the pattern, given as JSON object mapping parameter names to parameter definition

A parameter definition is a JSON Objects with:

type - the data type. One of path, number, url, comparator, list… (this needs to be defined)
…

Example 5

{
  "id": "MandatoryChild",
  "description": "Checks that an element contains at least one other element",
  "parameters": {
    "parent" : { "type": "path" },
    "child": { "type": "path" }
  }
}

8 Constraint Template

A Constraint Template is a JSON object with the following fields:

id (OPTIONAL) - identifier of the template. SHOULD be an URI.
pattern (REQUIRED) - identifier of a constraint pattern.
sentence (REQUIRED) - a JSON object with fields being [language tags] and values being JSON arrays of fragments.
parameters (OPTIONAL) - a JSON object with some fields being parameter names of the constraint pattern and values matching to the parameter type.

If parameter contains all parameters of the constraint template, the constraint template can automatically be converted into a constraint.

Sentences and fragments can be converted into messages in Unicode MessageFormat 2.0 (MF2) and a later version of this standard may support more of its features for better internationalization.

Example 6

{
  "pattern": "MandatoryChild",
  "sentence": {
    "en": [ 
      { "text": "Each" },
      { "parameter": "parent" },
      { "text": "has at least one" },
      { "parameter": "child" },
      { "text": "." }
    ] 
  }
}

A constraint template.

9 Processor

A processor gets a document with known base format and a set of [constraints] as input and returns an [analysis report] as output.

10 Analysis Result

The analysis result format will be based on Validation Error Format.

11 References

11.1 Normative References

Dürst, M. and Suignard, M.: Internationalized Resource Identifiers (IRIs). RFC 3987, January 2005. https://tools.ietf.org/html/rfc3987
Berners-Lee, T. and Fielding, R. and Masinter, L.: Uniform Resource Identifier (URI): Generic Syntax. RFC 3986, January 2005, http://www.rfc-editor.org/info/rfc3986.
Bradner, S.: Key words for use in RFCs to Indicate Requirement Levels. BCP 14, RFC 2119, March 1997, http://www.rfc-editor.org/info/rfc2119.
Bray, T.: The JavaScript Object Notation (JSON) Data Interchange Format. RFC 8259, December 2017. https://tools.ietf.org/html/rfc8259

Phillips, A. and Davis, E.: Tags for Identifying Languages. RFC 5646: BCP 47, September 2009. https://tools.ietf.org/html/rfc5646
Voß, J: Validation Error Format. May 2026 https://gbv.github.io/validation-error-format/

11.2 Informative references

JSON Schema schema language

J. Clark and S. DeRose: XML Path Language (XPath) Version 1.0. W3C Recommendation, November 1999. https://www.w3.org/TR/xpath-10/
…

Appendices

Base Formats

Base Format	Path Languages
`xml`	`xpath`
`json`, `yaml`	`jsonpath`, `jsonpointer`
`csv`	`rfc7111`, `column` …
`avram`	…
`rdf`	…

JSON Schemas

Constraint, Constraint Patterns and Constraint Templates can be validated each with one of the following non-normative JSON Schemas:

…

Examples

Cardinality Constraint Pattern

{
  "description": "Checks that an element exists a specific number of times"
  "parameters": {
    "element": {
      "type": "path",
      "description": "The element being counted"
    },
    "comparator": {
      "type": "comparator",
      "description": "Whether the number of times must be equal, larger, or smaller than the cardinality"
    },
    "cardinality": {
      "type": "natural-number",
      "description": "Number of times the element must exist"
    }
  }
}

AND pattern

{
  "description": "Combines multiple constraints",
  "parameters": {
    "constraint": {
      "type": "constraint",
      "repeatable": true
    }
  }
}

SHACL Constraint Pattern

{
  "id": "XSDValidation",
  "description": "Checks that XML data is valid against an XML Schema",
  "models": [ "xml" ],
  "parameters": {
    "schema" : {
      "type": "url"
      "description": "Location of the Schema"
    }
  }
}