[Json] Re: Proposal for use of JSON Text vs JSON Document in JSON Schema

[David Kemp <[e-mail]>]

s/JSON document/JSON value/g

As Carsten said, there is already a clearly-defined word for the concept of
"contrasting schema values with resources" and "an instance value is a unit
of serialization".  That word is "value", not "document".  Using a word in
a way that contradicts its widely-understood meaning is a recipe for
confusion.

Regards,
David

On Tue, May 19, 2026 at 12:08 PM Henry Andrews <andrews_henry=
[e-mail]> wrote:

> JSON Schema does not work directly with JSON Text.  If the WG wants to
> call what it works with an "information set" (by analogy with XML, I
> assume), that's fine with me.
>
> The "JSON Document" concept is about _contrasting documents with
> resources._  It's only relationship to serialization formats is that a
> document is a unit of serialization, while a resource is a unit if
> identification (identified by an absolute-URI assigned by $id).  Documents
> can contain multiple resources.  The primary use case of this is bundling
> multiple schema resources into a single document for ease of distribution,
> as some tools do not like references that cross documents, but are OK with
> references that cross resource boundaries within a document.
>
> "JSON Text" is a serialization format (application/json).  This is a
> different thing, which is only relevant to the media type
> (application/schema+json, or whatever +json name we use), which exists to
> facilitate interoperable exchange of schemas (not processing- processing is
> independent of serialization, as illustrated by the fact that nearly every
> project I've ever been involved with writes schemas in YAML for authoring
> convenience).
>
> thanks,
> -henry
>
> On Tuesday, May 19, 2026 at 05:16:45 AM PDT, Salz, Rich <rsalz=
> [e-mail]> wrote:
>
>
>
>    - *My proposal*: This proposal is to keep "*JSON Document*".  I make
>    this proposal  because  existing JSON Schema specs and usage haven't
>    experienced problems around the term "JSON Document".  It's also biased
>    towards my own interpretation of "readability". I believe we can address of
>    the related concerns while not fundamentally changing terminology, with
>    these changes in the proposal:
>
>
> I believe the reason why there have been no problems is that this document
> was known to be “informal” and not something with strict language
> conventions that you typically see from an standards organization. We’ve
> already seen disagreement from experts[1]: "JSON Schema document is not
> JSON text…”
>
> I think the WG needs to first decide if it’s working with an information
> set or JSON Text, and then make the appropriate comprehensive changes in
> the draft. I suggest that if/when this is done, that it be the *only*
> content in a published version of the draft.
>
> [1]
> https://mailarchive.ietf.org/arch/msg/json/cYRrRFk5jLHtpmbg7IPzRaxTeLc/
> _______________________________________________
> json mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
> _______________________________________________
> json mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
>