formatMinimum (v5 proposal) - sgpinkus/json-schema GitHub Wiki

THIS WIKI IS OBSOLETE. PLEASE SEE THE NEW JSON-SCHEMA-ORG/JSON-SCHEMA-SPEC REPOSITORY.

NOTE: Added to new org as issue: https://github.com/json-schema-org/json-schema-spec/issues/116

Proposed keywords

  • formatMinimum
  • formatMaximum
  • formatExclusiveMinimum
  • formatExclusiveMaximum

Purpose

Currently, numeric values can be constrained using minimum/maximum.

However, non-numeric formatted data cannot have such constraints, even when the format has a clear ordering. These additional keywords would allow for minimum/maximum constraints on such data.

Values

The values of formatMinimum/formatMaximum may be any JSON value. Particular values of format may imply a particular shape of data.

The values of formatExclusiveMinimum/formatExclusiveMaximum are booleans.

Validation

Validation is very similar to minimum/maximum/exclusiveMinimum/exclusiveMaximum. The only differences are:

  • All data types are constrained (not just numbers)
  • Instead of numerical ordering, an alternative ordering is used, selected based on the value of format.
  • Validation of these keywords is completely optional, exactly like format. Support for one of these keywords does not imply partial or complete support for any of the others.

Example

{
    "type": "string",
    "format": "date-time",
    "formatMinimum": "2013-01-01T00:00Z"
}

In this example, the schema specifies that the string should be an ISO 8601 date-time, at some point after New Years 2013 (GMT).

Note that because ISO 8601 date-times can specify a timezone (and timezone differences should be accounted for in comparisons), there is no dictionary-ordering of strings that would correctly enforce this constraint - this constraint can only be expressed in a format-aware way.

Concerns

Using format-specific ordering is deliberately designed to avoid the localisation/"collation" issues that would be presented by string orderings, so we dodge a bullet there.

format values mentioned in the spec should also mention an expected ordering, if applicable.

This still does not provide a canonical way to specify localised dictionary orderings for strings. A format pattern like "text-de" might help, but should we specify that, or leave it up to schema authors/consumers to agree on something?