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

[John Carlson <[e-mail]>]

Let’s not do “schema instance” I was thinking I could convert JSON schema
text to XSD text, and was going wait a minute.

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

> Inventing "schema instance" for schemas would be massively confusing to
> all of the users and implementors out there.  Yes, schemas are instances of
> their metaschemas, but that's like saying someone who is a parent is also a
> child of *their* parents.  It is a true statement, but when choosing
> whether to refer to them as parents or children, the context matters.  The
> JSON Schema community has used "schema instance" for _instances_ (validated
> input), not schemas, for well over a decade.
>
> I am enthusiastic about clarifying ambiguous language, which might include
> dropping long-used terminology in favor of something new (or old, from a
> better-established lineage of specifications).  But appropriating a term
> that has a well-established meaning and *redefining it to mean something
> else* is just going to create confusion.
>
> > A namespace is not a resource.
>
> Something that is identified by a Uniform Resource Identifier is, by
> definition, a resource.  There is absolutely not requirement that resources
> be physical things.  A resource can be an abstract concept with no physical
> manifestation at all.
>
> thanks,
> -henry
>
>
> On Tuesday, May 19, 2026 at 03:46:00 PM PDT, David Kemp <[e-mail]>
> wrote:
>
>
> 1. Because the JSON metaschema is a JSON value, it defines a Schema type
> and every JSON Schema value is an instance of that type.  This is the key
> to everything.
> 2. JSON Schema instances can be serialized as JSON documents or YAML
> documents. (Using an IM the same JSON Schema instance could be serialized
> as an XML document.)
> 3. The $id keyword is an absolute IRI that defines the namespace of every
> Schema instance, allowing qualified references to every
> namespace#$defs-name type (using fragment notation) or prefix:$defs-name
> (using QNAMEs if prefix abbreviations are assigned to namespaces).
> 4. Every type defined in every Schema instance is a unit of serialization.
>
> To take a random example, the JSON Schema for CycloneDX at
> https://github.com/CycloneDX/specification/blob/master/schema/bom-1.6.schema.json
> has a namespace "$id": "http://cyclonedx.org/schema/bom-1.6.schema.json",
> an unnamed root type with two required properties, and finally at line 534
> it has top-level definitions
> that could be referenced externally, starting with cdx:refType if the
> referencer defines "cdx" as the prefix for the referenced namespace.
>
> That file is a JSON document that defines a "bom-1.6.schema".  There could
> also be a YAML document ".../bom-1.6.schema.yaml" that defines the
> identical "bom-1.6.schema".  They are both instances of the JSON metaschema
> so you can call the value a "schema instance" or "schema value" or simply a
> "schema", whereas a CycloneDX value parsed from a JSON or YAML document
> would be a "cdx-bom-1.6 instance" or "cdx-bom-1.6 value" or simply a
> "cdx-1.6 bom".  The $id namespace should be semantically a URN even if it
> has an http:// scheme, with no file pathnames or extensions.
>
> I think of "resource" as being a physical thing, so the
> bom-1.6-schema.json file and bom-1.6-schema.yaml file are different
> resources that parse to the identical schema. The identical files copied to
> a different server would be two additional different resources, for a total
> of 4. If that is what resource means, then a document is a resource. A
> namespace is not a resource.
>
> Regards,
> David
>
> On Tue, May 19, 2026 at 2:53 PM Henry Andrews <[e-mail]>
> wrote:
>
> David and Carsten,
>   I agree that "JSON value" is pretty close to what we have been doing
> with "JSON Schema document", but Carsten does note part of the concern here.
>
> I think we've also gotten some wires crossed a bit, though, as we are
> talking about the _schemas_, not the things that schemas describe (which,
> IIRC, in the latest draft we call "inputs" prior to validation, and then
> "instances" if they pass validation.  In prior drafts, we used "instance"
> rather more broadly).
>
> So what we're really discussing here is more akin to "schema document"
> than "JSON document"/"JSON value".  We call it a "JSON Schema document"
> because it is "JSON Schema" that we're talking about, but the "JSON" part
> is not the important part.  It's schema documents vs schema resources.
>
> Therefore, we really can't call these things "instances" as that is what
> things that the schema describes have been called for many years.
>
> I'm going to try to summarize the various concepts:
>
> * JSON Schema in the form of JSON text: application/schema+json or similar
> media type; A serialization format to allow interoperable exchange of
> schemas
> * JSON Schema in the form of YAML text: (application/schema+yaml or
> similar media type;  Same as above, but with YAML.  If we want to add that.
> * JSON Schema as a unit of serialization: currently "JSON Schema
> document", but under debate.  Not required to have ever been actual JSON.
> * JSON Schema as an identifiable unit: "JSON Schema resource"; identified
> by an absolute-URI (e.g. a "primary resource" in terms of RFC3986)
> * JSON input (and potential instance) in the form of JSON text:
> application/json, possibly with a profile param, or possibly a media type
> like application/schema-instance+json; a media type or media type parameter
> for interoperably associating an input (potential instance) with a schema
> in exchanges such as via HTTP
> * input (and potential instance), independent of serialization format, if
> any: I think we just call this the input or instance?  We don't make a
> particularly big deal about serializing inputs/instances, IIRC.
>
> BTW I am really appreciating the effort to bring rigor to the
> terminology.  It's something we always struggled with.
>
> thanks,
> -henry
>
> On Tuesday, May 19, 2026 at 09:54:38 AM PDT, Carsten Bormann <[e-mail]>
> wrote:
>
>
> On 2026-05-19, at 18:41, David Kemp <[e-mail]> wrote:
> >
> > 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.
>
> Right, I talked about the difference between the JSON text and the JSON
> value (value that is parsed/ingested from JSON).
>
> However, people also seemed to want to have a “whole” vs. “part”
> distinction.
> If we need to avoid the term “document”, the JSON value that is the whole
> thing the JSON schema model is trying to describe could be called “JSON
> instance”.
> We also need a word for the JSON value that describes the whole JSON
> schema model — I obviously like the word model, but I’m not going to make a
> proposal.
> (Note also that the model may be composed from more than one JSON Schema
> value/text.)
>
> (If you want to save a bit of time, you might want to have a look how we
> solved a related terminology problem in RFC 9880.)
>
> Grüße, Carsten
>
> _______________________________________________
> json mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
>