Nesting/grouping definitions in schema defs

[b-wils]

Is it allowed to use objects within JSON schema defs to group/organize children definitions? Something like-

{
    "$defs": {
        "group1": {
            "def1": {
                // schema definition
            },
            ...
        },
        "group2": {
            ...
        }
    },
    "$ref": "/$defs/group1/def1" 
}

The specs at https://json-schema.org/draft/2020-12/json-schema-core#name-schema-re-use-with-defs state-

This keyword's value MUST be an object. Each member value of this object MUST be a valid JSON Schema.

It's unclear to me if object with other objects is valid or not.

This behavior is useful for us to when working with a large schema with lots of defs.

[jdesrosiers]

Unfortunately, it isn't possible to support nested $defs in that way. It can sort of work in most cases, but there are consequences you incur that I wouldn't recommend. The problem is that if we allow nested $defs, it becomes ambiguous what is a schema and what is an object. Take this example.

{
  "$defs": {
    "foo": {
      "title": { "type": "date" }
    }
  }
}

If #/$defs/foo is a schema, then the title keyword is invalid because it's not a string. If it's an object and #/$defs/foo/title is the schema, then it's invalid because "date" is not a valid type. There's no way for tools to detect that you've made a mistake or what mistake you've made.

If you really want to have nested $defs, there is a way, but it won't necessarily work with all validators and has consequences. The meta-schema validates that the values of the $defs object are schemas and in JSON Schema, unknown keywords are ignored. So, as long as you don't use a keyword name (like title) as a definition label, you can avoid clashes with keywords. Then in most validators, your references to the schema will work as expected. The consequence is that your nested schema will be ignored by all tools you use for writing schemas. So, you loose niceties like schema validation and autocomplete in editors because the editor doesn't know you expect it to be a schema. Because your schemas aren't validated, errors could get though and blow up at runtime. Even if you catch these runtime errors in tests, it's generally harder to debug the validator blowing up than a the result of schema validation step. I would strongly recommend that nested $defs isn't worth those consequences.

The only way things like schema validation and autocomplete can be supported is if it isn't unambiguous whether a location is a schema or an object. Because schemas are represented as objects, supporting nested $defs isn't possible. The alternative you could use to avoid this ambiguity is to use a schema with only $defs to create nesting. That makes it unambiguous what is a schema. For example,

{
  "$ref": "#/$defs/a/$defs/b",
  "$defs": {
    "a": {
      "$defs": {
        "b": { ... }
      }
    }
  }
}

This behavior is useful for us to when working with a large schema with lots of defs.

I don't know the details of you specific circumstance, but generally my advice in these situations is, don't write large schemas. Break it down into smaller pieces and compose them as needed. You can use a bundler if you need to distribute them as a single schema, but it's much easier to work with smaller schemas when developing. Usually, each of your definitions can be their own schema and the directory structure you use to store those schemas is how you organize them. What you end up with is $defs only being used rarely for small things specific to the relatively small schema it appears in.

It's unclear to me if object with other objects is valid or not.

I think the text you quoted is pretty clear. Perhaps you tried using nested $defs and noticed that it worked and are confused because the spec seems to say it shouldn't. It can work, but that's not how it's intended to work and it's really not worth it.

[b-wils]

Thank you for the detailed explanation. This makes a lot of sense the issues with using schemas in this way, and we'll be looking at alternatives.

I think the text you quoted is pretty clear.

It's not clear to me what part of the spec makes the nesting invalid. Assuming no keywords are used, this seems like it would fall under the empty schema definition which would be valid. For posterity, perhaps this could be better clarified $defs section in the spec?

And yes you are spot on that nesting has worked with other tools which led to the confusion.

[jdesrosiers]

Oh, I see what you mean. It's not the nesting that's invalid. As you say, it's technically a valid schema. The thing that's invalid is referencing a location that's not known to be schema. That's covered in 9.4.2 References to Possible Non-Schemas. Technically, it's not invalid, it's undefined behavior. $ref is only for referencing schemas, so if you try to reference a location that's not known to be a schema, you get whatever the tool decided to support. Some tools are stricter than others. Some will just treat whatever the reference points to as a schema and try to evaluate it, while others will check that the location is a schema and throw and error if it isn't.

When I said it's not possible to support, nested $defs, I actually mean it's not possible to determine that your nested definition is a schema and therefore can't be reliably referenced.