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

[David Kemp <[e-mail]>]

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
>
>