[jts] Refine min* and max* in field constraints

[pwalsh]

A field constraint descriptor supports the following keys related to minimum and maximum values: minLength, maxLength, minimum, maximum.

The spec describes them as follows:

• minLength – An integer that specifies the minimum number of characters for a value
• maxLength – An integer that specifies the maximum number of characters for a value
• minimum – specifies a minimum value for a field. This is different to minLength which checks number of characters. A minimum value constraint checks whether a field value is greater than or equal to the specified value. The range checking depends on the type of the field. E.g. an integer field may have a minimum value of 100; a date field might have a minimum date. If a minimum value constraint is specified then the field descriptor MUST contain a type key
• maximum – as above, but specifies a maximum value for a field.

I think the intentions are good, but the spec is lacking clarity. The examples don't consider how these may or may not apply to all types. Just thinking out loud, but the following would be helpful for my reading of the spec:

• Rename minimum > minValue and maximum > maxValue (consistent with the *Length keys, and more explicit in meaning)
• Define behaviour of all min* and max* constraints for each builtin type/format. Example:
  • *Length constraints: length of each chars in string, items in array and keys in object
    • decide what would return for other types like binary, boolean, etc.
  • *Value constraints: min and max for each date, time, datetime, number, integer
    • decide what would return for other types like unformatted strings

[rufuspollock]

@pwalsh excellent suggestions

@ldodds @paulfitz @jpmckinney any thoughts here?

[jpmckinney]

Re: rename: the names were chosen to match JSON Schema. I think the use of common terms is more important than the slight improvement in clarity.

FYI, in JSON Schema, minimum and maximum apply to number and integer types only; minLength and maxLength apply to the string type only. It has minItems and maxItems for arrays, and minProperties and maxProperties for objects.

I don't think minimum/maximum makes sense for string, and I don't think minLength/maxLength makes sense for boolean, number, integer. It should just cause an error like "unexpected type 'string' for field with 'minimum' constraint".

[pwalsh]

@jpmckinney the thing is here, JSON Schema has very explicit definitions for "validation keywords" (which loosely map to constraints in JSON Table Schema) per type.

JSON Table Schema doesn't, and, at least for me, that creates some ambiguity.

As you note, the existing spec for min* and max* constraints do not make sense for all types. So, if they are going to stay exactly how they are, I think we should:

• Clarify the types that they do support, with examples
• Clarify the expected behaviour on other types (throw, or ignore with optional warning)

Still, I do prefer my suggestion above with naming. I'm all for aligning with JSON Schema where possible (like primitive types), but in this case, constraints in the current form do not really map so well to "validation keywords" (the later being much more detailed and type-specific).

[ldodds]

I'm not sure about the rename suggestion, but don't feel strongly either way. I believe we (ODI, etc) do have some schemas using this naming so would prefer to avoid breaking changes.

+1 on clarifying the specification further.

[brew]

This is my suggestion based on trying to implement constraints for jsontableschema-py. I'm thinking that minimum and maximum should only apply to numbers and dates/times: so integer, number, date, time and datetime. This maps well with the python comparison operators.

And maxLength/minLength only apply to sequence types: string, array, object, possibly also geopoint and geojson. This maps naturally with the len() python builtin.

For types that don't support a particular constraint, an exception is raised ConstraintNotSupported e.g.:

ConstraintNotSupported: Field type 'null' does not support the minLength constraint

[pwalsh]

Hey @brew I wholeheartedly agree, and I'm glad to see the issues I originally raised when we started the python lib are raised again now that you are working on it :).

I think the way you have implemented it is correct, and we should update the spec to reflect this.

Would you be happy to do a pull request on the spec that clarifies the min* max* constraints?

[rufuspollock]

@pwalsh @brew agree. Could you craft a pull request and submit.

[pwalsh]

Closing as @brew made the PR and it has been merged.