Clarify how schemas embedded inside other document types are identified

[gregsdennis]

Core 4.3.5 has the following:

The root schema is the schema that comprises the entire JSON document in question. The root schema is always a schema resource, where the URI is determined as described in section 9.1.1.

along with the following as an editor's note:

Note that documents that embed schemas in another format will not have a root schema resource in this sense. Exactly how such usages fit with the JSON Schema document and resource concepts will be clarified in a future draft.

I assume this is to cover cases like OpenAPI, which embed JSON Schema directly into their own document, which means that the entire document cannot be the root schema.

We need to clarify this.

[jviotti]

The root schema is the schema that comprises the entire JSON document in question.

This doesn't seem to make sense in the context of i.e. OpenAPI. The entire JSON document in question in that case would be the OpenAPI specification document. Maybe we should say something like "The root schema is the top-level schema resource for the schema in question"?

Note that documents that embed schemas in another format will not have a root schema resource in this sense.

Is this true though? If I have an OpenAPI specification document where on a request input I defined a schema with potentially a nested schema resource, wouldn't I call the top-level schema from that request input the root schema resource for that specific JSON Schema?

[gregsdennis]

The root schema is the top-level schema resource for the schema in question

Then you have a problem with the next sentence that says that a root schema is always a resource. This is to allow for the case where a schema embedded in some other document (e.g. OpenAPI or the tests) wants to declare $schema but not $id.

You can't call it a resource yet because it hasn't been declared to be one yet.

It all does need to be massaged out.

[jviotti]

Ah, good point. It does need clarification indeed.