Skip to content

Clarify how schemas embedded inside other document types are identified #1513

Closed
@gregsdennis

Description

@gregsdennis
Member

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.

Activity

added this to the stable-release milestone on May 23, 2024
jviotti

jviotti commented on Jun 20, 2024

@jviotti
Member

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

gregsdennis commented on Jun 20, 2024

@gregsdennis
MemberAuthor

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

jviotti commented on Jun 21, 2024

@jviotti
Member

Ah, good point. It does need clarification indeed.

gregsdennis

gregsdennis commented on Nov 12, 2024

@gregsdennis
MemberAuthor

I think this was likely cleared up by #1537.

@json-schema-org/spec-team can someone verify, please?

jdesrosiers

jdesrosiers commented on Nov 16, 2024

@jdesrosiers
Member

can someone verify, please?

That text hasn't changed. The issue still exists.

moved this from In Discussion to Awaiting PR in Stable Release Developmenton Apr 26, 2025
moved this from Awaiting PR to In Progress in Stable Release Developmenton Apr 26, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status

    Done

    Relationships

    None yet

      Development

      Participants

      @jdesrosiers@jviotti@gregsdennis

      Issue actions

        Clarify how schemas embedded inside other document types are identified · Issue #1513 · json-schema-org/json-schema-spec