Is it mandatory to use $defs for reused blocks

[martpio]

I have a bit of a concern regarding the use of the $defs keyword.

According to the description in Understanding JSON Shema "the $defs keyword gives us a standardized place to keep subschemas intended for reuse in the current schema document."

What if I wanted to keep such data in another place? Is this considered bad design, or is it acceptable? I'll give two different situations, both of which validate correctly.

1. Split into sections inside $defs

Is it necessary here to make a new $defs for each type group, or is one at the main level enough?

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    
    "type": "object",
    "properties": {
    	"a": {"$ref": "#/$defs/TypeGroupOne/Foo"}
    },
    "required": ["a"],
      
    "$defs": {
    	"TypeGroupOne": {
            "Foo": { "type": "integer"},
            "Bar": { "type": "string"}
        },
        "TypeGroupTwo": {}
    }
}

2. Defining types at the main file level

This is mainly for use in auxiliary files - for example, we have main_schema.json and type_definitions.json. Is it necessary to use $defs at the type_definitions.json level? Since in main_schema.json we, for example, refer to the types defined there anyway via"$ref": "type_definitions.json#Foo".

File type_definitions.json:

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    
 	"TypeGroupOne": {
        "Foo": { "type": "integer"},
        "Bar": { "type": "string"}
    },
    "TypeGroupTwo": {}
}

[jdesrosiers]

The only problem with that approach is that you don't get meta-schema validation if put your schemas somewhere that the dialect doesn't recognize as a schema. Take this schema for example.

{
  "$defs": {
    "foo": { "type": "invalid" },
    "bar": {
      "nested": { "type": "invalid" }
    }
  }
}

Implementations are likely to recognize #/$defs/foo/type has an error, but not #/$defs/bar/nested/type. Instead of telling you your schema has an error in the normal way, it will probably just blow up and you'll have to sift through the wreckage to figure out what went wrong.

If you want to have nested definitions, you could use $id to create a separate context. It's a bit more verbose, but it will be safer.

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    
    "type": "object",
    "properties": {
    	"a": {"$ref": "TypeGroupOne#/$defs/Foo"}
    },
    "required": ["a"],
      
    "$defs": {
    	"TypeGroupOne": {
            "$id": "TypeGroupOne",
            "$defs": {
              "Foo": { "type": "integer"},
              "Bar": { "type": "string"}
            }
        },
        "TypeGroupTwo": {
          "$id": "TypeGroupTwo",
          "$defs": {}
        }
    }
}

Edit: Actually, you don't need to the $id. The nested $defs is enough. The $id just makes the referencing URIs a little nicer.

[martpio]

Thank you. That clarifies it.