Add section on schema resource and compound schema resource

[Temidayo32]

What kind of change does this PR introduce?

Issue Number:

• Related to Create a JSON Schema Glossary Page or Site #266

Summary

As discussed in #266, this PR adds two sections to the glossary page.

Does this PR introduce a breaking change?

No

[github-actions]

Welcome to the JSON Schema Community. Thanks a lot for creating your first pull request!! 🎉🎉 We are so excited you are here! We hope this is only the first of many! For more details check out README.md file.

[gregsdennis]

A schema resource is a schema which is canonically identified by an absolute URI.

This is just taken verbatim from Core 4.3.5. The idea of this glossary is to make things a bit more plain.

This implies all root/parent schemas are schema resources as they can be identified by an absolute URI.

This isn't precisely true.

{ "type": "object" }

is a root schema, but it's not a resource because it's not identifiable.

---

We should say that a schema resource is any schema or subschema which carries an $id keyword and then re-iterate the specification's suggestion that all root schemas should carry an $id keyword.

[jdesrosiers]

Greg, I think you've uncovered an inconsistency in the spec. I think that your example has to be considered a Schema Resource. Here's a slightly more complex schema to explain why.

{
  "type": "object",
  "properties": {
    "foo": { "$ref": "https://example.com/schema/foo" }
  },
  "$defs": {
    "foo": {
      "$id": "https://example.com/schema/foo",
      "type": "string"
    }
  }
}

The root schema is one of the Schema Resources that makes up this Compound Schema Document, but it doesn't have an identifier. If we don't consider the root schema a Schema Resource, then this wouldn't be a Compound Schema Document, which doesn't make sense. There has to be an exception so that the root schema doesn't need to have $id.

[gregsdennis]

Suggested change

	The URI serves as a canonical identifier for the schema. This allows it to be referenced and reused in other schemas. Consequently, all schema resource must maintain semantic clarity, without which reusability will be difficult.
	The value in the `$id` keyword should resolve to an absolute URI, which serves as a canonical identifier for the schema. This allows it to be referenced and reused in other schemas.

Consequently, all schema resource must maintain semantic clarity, without which reusability will be difficult.

I'm not sure what you mean by "semantic clarity".

[jdesrosiers]

In addition to my 👍 on Greg's suggested change, I suggest dropping the word "canonical". The lay-person doesn't know that word and it's not necessary to convey the concept.

[gregsdennis]

Compound schema resource is vital when working with multiple schema resources.

I'm not sure this is true. A system can happily work with every resource in its own document. Ideally, this is the way it should be done, but that's not always practical.

Also bundling, as described by that link, isn't the only reason to embed resources. In an OpenAPI document block, each schema could have its own identifier, making it a distinct resource which could be $ref'd from anywhere.

[gregsdennis]

The spelling fix is appreciated, but the wording here is weird. Can we clean this up while we're here?

[jdesrosiers]

The correct term is "Compound Schema Document".

[jdesrosiers]

A compound schema resource is a JSON document which has multiple embedded JSON schema resources.

You can't use the word "embedded" in this sentence. The root schema counts as one of the "multiple" Schema Resources, but it isn't "embedded". So, the way this is currently worded, there would have to be two embedded schemas (three Schema Resources) before it would be considered a Compound Schema Document.

[jdesrosiers]

It is important to note that for a schema to be embeddable it must define a $id keyword, which is used to hold its unique identifier.

Maybe it's just me, but it feels awkward to phrase it like this. I would say it the other way around. A subschema is an embedded schema if it has an $id keyword.

[jdesrosiers]

These embedded schema resources collectively define various aspects or features of the overall schema.

"Features" isn't the right word here. We usually use that term to refer to features of JSON Schema as a language. I think the word you're looking for here is "constraints". We say that each keyword in a schema adds a constraint to the schema.

[jdesrosiers]

A schema resource is a schema which is canonically identified by an absolute URI.

I'd drop the word "canonically". It's just techno-babel that's not necessary to describe the concept to lay-people.

[jdesrosiers]

Greg, I think you've uncovered an inconsistency in the spec. I think that your example has to be considered a Schema Resource. Here's a slightly more complex schema to explain why.

{
  "type": "object",
  "properties": {
    "foo": { "$ref": "https://example.com/schema/foo" }
  },
  "$defs": {
    "foo": {
      "$id": "https://example.com/schema/foo",
      "type": "string"
    }
  }
}

The root schema is one of the Schema Resources that makes up this Compound Schema Document, but it doesn't have an identifier. If we don't consider the root schema a Schema Resource, then this wouldn't be a Compound Schema Document, which doesn't make sense. There has to be an exception so that the root schema doesn't need to have $id.

[jdesrosiers]

In addition to my 👍 on Greg's suggested change, I suggest dropping the word "canonical". The lay-person doesn't know that word and it's not necessary to convey the concept.