Subject: [Json] Notes on json-schema-language-00

From: Tim Bray <[email-masked]>
Date: Mon, 6 May 2019 21:40:09 -0700

I've now had time to give the draft a read.  I think it shows promise and
would be useful in meeting needs I'm currently facing at work.  I'd like to
talk it over and if we can move it forward a bit and get significant
community support for a revised draft, would be interested in proposing we
spin up a WG to see if there's IETF consensus to be had, and in
volunteering to invest cycles to help with the process.  If anyone objects
to using this mailing list for such a conversation, please say so.
Obviously since it's on github we could file issues there if that's what
people would prefer.

Ulysse, if we do have such a discussion, please don't charge off and start
revising your draft; it's helpful to keep the document stable for a while
while we figure out whether there's consensus.

First, a question: I'm a little out of touch with the json-schema work.  Is
this designed to be a compatible subset?  Or is there any other
relationship?  Depending on the answer, we might want to consider a name
for this other than "JSON Schema Language".

Some things to discuss:

   1. There are problems with JSON terminology; "JSON text", "field",
   "name"/"value", "corresponding". But these are easy to fix.
   2. I'd consider enriching the type range a bit, we don't have to stick
   strictly with JSON's impoverished diet
   1. In 4.1, I think it'd be useful to specify integer/float, bearing in
      mind the reasonableness in behavior discussed in the intro thread.
      2. I'd add a timestamp type (RFC3339 strings)
      3. I'd really want to add an enum type (constraint on JSON string
      value)
   3. I'd introduce lots of examples early in section 4, to show how each
   of the keywords might be used.
   4. In 4.4, I suggest the URI reference resolution procedure is way too
   complicated, and needn't involve the "id" element at all.
   5. Probably error objects should allow extra fields such as line/column
   numbers and human-readable explanations of what went wrong.

---

From: Rob Sayre <[email-masked]>
Date: Mon, 6 May 2019 23:22:50 -0700

Would a JSON message with such a schema be self-describing? If not, what
benefit would this scheme provide over Thrift or Protobuf? It seems like it
would be strictly worse.

- Rob

On Mon, May 6, 2019 at 9:40 PM Tim Bray <[email-masked]> wrote:

> First, a question: I'm a little out of touch with the json-schema work.
> Is this designed to be a compatible subset?  Or is there any other
>    5. Probably error objects should allow extra fields such as
>    line/column numbers and human-readable explanations of what went wrong.
>
> _______________________________________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/json
>

---

From: Ulysse Carion <[email-masked]>
Date: Mon, 6 May 2019 23:32:47 -0700

On your direct comments to me:

> Ulysse, if we do have such a discussion, please don't charge off and start revising your draft; it's helpful to keep the document stable for a while while we figure out whether there's consensus.

You got it. The document will remain stable.

> First, a question: I'm a little out of touch with the json-schema work.  Is this designed to be a compatible subset?  Or is there any other relationship?  Depending on the answer, we might want to consider a name for this other than "JSON Schema Language".

No, it is not meant to be a compatible subset. There is no formal
relationship between the two projects, although I have contributed to
both. In the interest of not letting the perfect be the enemy of the
good, I simply chose the most apt name I could think of. I agree that
"JSON Schema Language" will likely provoke confusion, and that it may
require a renaming.

On the broader points:

> There are problems with JSON terminology; "JSON text", "field", "name"/"value", "corresponding". But these are easy to fix.

Agreed. Loosely speaking, I suspect there's a sort of linguistic yoga
which I didn't manage to muster in the I-D's language. Hopefully the
intention is clear, and I trust the language can be tightened.

All three of your suggested extensions were originally in the first
draft, but I ultimately cut them out to produce a sort of minimum
viable proposal which didn't extend JSON at all, just to keep it
simple at first.

1. On integers: the use-case likely will be to produce the equivalent
of an integer in some programming language, no? If so, would we need
to restrict data further, to perhaps (u)int(64, 32, 16, 8)?
2. On timestamps: I agree that RFC 3339 is the enlightened choice of
timestamps, and that their validation is part of the tedium that is
checking JSON validity for APIs. But we are bound to disappoint some
by choosing this format at the expense of others. I think a case can
be made that validating timestamps is an applicative, not a schema,
concern.
3. On enums: I agree that these are desirable. They were dropped at
the last minute because I wanted to at first ship something that
didn't extend JSON at all. As long as we limit ourselves to enums of
strings, that is -- I'm skeptical of numerical or other sorts of enums
being worth adding.

I ultimately think these would all be valuable extensions. But I would
urge restraint in going any further. The language shouldn't have
constructs any more powerful than the average, non-exotic type system.
on my view.

> I'd introduce lots of examples early in section 4, to show how each of the keywords might be used.

I agree that there's a dearth of examples in the opening. My concern
was that the examples would ultimately be mostly redundant with
examples in the validation section. But happy to change that if we
desire.

> In 4.4, I suggest the URI reference resolution procedure is way too complicated, and needn't involve the "id" element at all.

Agreed that it's complicated.

What would you propose as an alternative? Should inter-document
references still be possible? Perhaps the "id" element is omitted, and
instead this information is provided out-of-band?

> Probably error objects should allow extra fields such as line/column numbers and human-readable explanations of what went wrong.

If the document precludes such additional fields, then that is a
mistake. Error messages should be so extensible, but I don't think we
should formalize any extensions at this time.

On Mon, May 6, 2019 at 9:40 PM Tim Bray <[email-masked]> wrote:
>
> I've now had time to give the draft a read.  I think it shows promise and would be useful in meeting needs I'm currently facing at work.  I'd like to talk it over and if we can move it forward a bit and get significant community support for a revised draft, would be interested in proposing we spin up a WG to see if there's IETF consensus to be had, and in volunteering to invest cycles to help with the process.  If anyone objects to using this mailing list for such a conversation, please say so.  Obviously since it's on github we could file issues there if that's what people would prefer.
>
> Ulysse, if we do have such a discussion, please don't charge off and start revising your draft; it's helpful to keep the document stable for a while while we figure out whether there's consensus.
>
> First, a question: I'm a little out of touch with the json-schema work.  Is this designed to be a compatible subset?  Or is there any other relationship?  Depending on the answer, we might want to consider a name for this other than "JSON Schema Language".
>
> Some things to discuss:
>
> There are problems with JSON terminology; "JSON text", "field", "name"/"value", "corresponding". But these are easy to fix.
> I'd consider enriching the type range a bit, we don't have to stick strictly with JSON's impoverished diet
>
> In 4.1, I think it'd be useful to specify integer/float, bearing in mind the reasonableness in behavior discussed in the intro thread.
> I'd add a timestamp type (RFC3339 strings)
> I'd really want to add an enum type (constraint on JSON string value)
>
> I'd introduce lots of examples early in section 4, to show how each of the keywords might be used.
> In 4.4, I suggest the URI reference resolution procedure is way too complicated, and needn't involve the "id" element at all.
> Probably error objects should allow extra fields such as line/column numbers and human-readable explanations of what went wrong.

---

From: Tim Bray <[email-masked]>
Date: Tue, 7 May 2019 09:03:03 -0700

Last time I checked, MustIgnore was  harder to implement in the binary
formats.  Is that still true?   That matters for some  of us.

In any case, JSON remains the lingua franca for lots of APIs and
event-driven systems, and upgrading its data typing a little seems worth
doing for its own sake, since there would be substantial cost and effort
involved in ripping it out and replacing it with anything else. Yes, I do
really want to start imposing types retroactively on existing message
streams.

On Mon, May 6, 2019 at 11:23 PM Rob Sayre <[email-masked]> wrote:

>> Ulysse, if we do have such a discussion, please don't charge off and
>> start revising your draft; it's helpful to keep the document stable for a
>> while while we figure out whether there's consensus.
>>
>>    2. I'd consider enriching the type range a bit, we don't have to
>>    stick strictly with JSON's impoverished diet
>>    1. In 4.1, I think it'd be useful to specify integer/float, bearing
>>       in mind the reasonableness in behavior discussed in the intro thread.
>>    3. I'd introduce lots of examples early in section 4, to show how
>>    each of the keywords might be used.
>>    4. In 4.4, I suggest the URI reference resolution procedure is way
>>    too complicated, and needn't involve the "id" element at all.

---

From: Rob Sayre <[email-masked]>
Date: Tue, 7 May 2019 10:24:22 -0700

> formats.  Is that still true?   That matters for some  of us.

Here's protobuf's docs:

https://developers.google.com/protocol-buffers/docs/proto3#unknowns

Anything that can be rolled out gradually usually has this property to some
extent.

> really want to start imposing types retroactively on existing message

I've never seen one of these systems save money vs switching to something
that deserializes directly to programming language data structures. It's
true that it might not be possible to switch from JSON for some use cases.

- Rob

>>> I've now had time to give the draft a read.  I think it shows promise
>>> and would be useful in meeting needs I'm currently facing at work.  I'd
>>> like to talk it over and if we can move it forward a bit and get
>>> significant community support for a revised draft, would be interested in
>>> proposing we spin up a WG to see if there's IETF consensus to be had, and
>>> in volunteering to invest cycles to help with the process.  If anyone
>>> objects to using this mailing list for such a conversation, please say so.