Subject: [Json] JCR comments

From: "Manger, James" <[email-masked]>
Date: Thu, 4 Dec 2014 11:10:45 +1100

JSON Content Rules (JCR) look pretty good. I have some comments on draft-newton-json-content-rules-04:

1. It is not quite right to say rules describe a particular JSON value. Rules describe a range of possible values; any particular values matches (or not) a given rule.
Suggestion for section 1:
Change "Figure 2 is an example of this language describing the JSON of Figure 1."
To "As an example, the JSON in Figure 1 matches the rules written in this language in Figure 2."

2. Change "100" to 100 (change string to number) in Figure 3 and A.2.

3. Section 3.1.1. There is no such thing as "the minimum number value possible to represent in JSON", nor any maximum (even if the 64-bit float range is a common implementation limit). Change the last 2 sentences of 3.1.1 to "If the minimum or maximum is not given then there is no limit in the corresponding direction."

4. Section 3.1.2: Change "prepending a URI template" to "appending a URI template".

5. Most of the string rules  (ip4, ip6, fqdn, idn, date-time, full-date, full-time, email, phone, base64) should be provided as examples of rules that are likely to be commonly useful, instead of making these specific syntaxes first-class citizens in the language. C.f. Some of the common ABNF rules (ALPHA, DIGIT, HEXDIG). They can probably be defined using the string /regex/ construct.
The spec could go on to say that these common rule names can be used without needing an explicit # include line.

6. 'base64' is not precise enough. The "normal" base64 alphabet and the URL-safe variant are both widely used, often omitting any "=" padding, sometimes allowing whitespace. One common 'base64' rule name defined in this spec should probably allow all those possibilities, even though a particular protocol that describes its messages with JCR may only allow a subset.

7. What sort of regex is expected? Probably need a reference.

8. The ABNF in section 5 hints that \/ and \\ are used to escape / and \ in a regex. Should state that explicitly in section 3.1.2.

9. Update RFC4627 references to RFC7159 in lots of places.

10. Section 3.5 has the following example, but no "&" semantics are defined. I think this functionality was dropped so drop the example as well.
  the_children { first_two_children & second_two_children }

11. Section 4.2 mentions "# ignore-unknown-members", but I suspect that has been replaced by "# pedantic".

12. To write a rule requiring a specific JSON value you need to enclose the value in < >, eg version "v" <1>. It would be a bit nicer if you could use JSON values directly (at least for primitives values), ie omit the < > brackets.

13. In the last paragraph of 3.4:
Change "The following example defines an array with an infinite number of child_value defined strings".
To "The following example defines an array that can have any number of child_value items".

14. 'uri' can be followed by a template, not just a URI. In the section 5 ABNF:
Change "uri-type        = "uri"     [ URI ] ; URI defined in RFC 3986".
To "uri-type        = "uri"     [ URI-Template ] ; URI-Template defined in RFC 6570".

15. I would be tempted to use 'true / false', instead of 'boolean'. Though I think the current syntax only allows '<true false>' as an alternative.

16. Why are "1" and "0" explicitly listed in the enum-items ABNF? Drop them. Drop "integer" as well from enum-items as it is a subset of "float" that is already included.

17. '/' would be a more intuitive separator of enum items than whitespace. '/' is used to separate alternative types in JCR and in ABNF.

--
James Manger

---

From: Andrew Newton <[email-masked]>
Date: Thu, 4 Dec 2014 15:38:46 -0500

Hi James,

Great review. My comments are in-line:

On Wed, Dec 3, 2014 at 7:10 PM, Manger, James <
[email-masked]> wrote:

>
>
>
> 5. Most of the string rules  (ip4, ip6, fqdn, idn, date-time, full-date,
> full-time, email, phone, base64) should be provided as examples of rules
> that are likely to be commonly useful, instead of making these specific
> syntaxes first-class citizens in the language. C.f. Some of the common ABNF
> rules (ALPHA, DIGIT, HEXDIG). They can probably be defined using the string
> /regex/ construct.
>
> The spec could go on to say that these common rule names can be used
> without needing an explicit # include line.
>

I had a phone call with Gearing Luff of the JSON Schema project, and type
extensibility was one of the discussion topics. I want to look at how they
are doing it and determine if there is a compatible way of referencing
types.

And the reason for doing so is that JCR might make a good "front-end" for
JSON Schema. Or in other words, a compact syntax compatible with JSON
Schema.

> 12. To write a rule requiring a specific JSON value you need to enclose
> the value in < >, eg version "v" <1>. It would be a bit nicer if you could
> use JSON values directly (at least for primitives values), ie omit the < >
> brackets.
>
>
Interesting. Along with item 17, it might be possible to drop the < >
altogether. Let me play with that.

> 15. I would be tempted to use ‘true / false’, instead of ‘boolean’. Though
> I think the current syntax only allows ‘<true false>’ as an alternative.
>
>
>
> 16. Why are “1” and “0” explicitly listed in the enum-items ABNF? Drop
> them. Drop “integer” as well from enum-items as it is a subset of “float”
> that is already included.
>
>
>
> 17. ‘/’ would be a more intuitive separator of enum items than whitespace.
> ‘/’ is used to separate alternative types in JCR and in ABNF.
>

Great idea. I'll look into this. It certainly simplifies the syntax for
enums.

-andy