Add option set the key used for a referenced type in $defs when deriving schemas

[michaeltlombardi]

Synopsis

I want to be able to derive JSON Schemas for my structs and ensure that the $defs key used for referenced schemas is the same as the $id keyword for those schemas to ensure my generated schemas follow the formalized specification for schema bundling in 2020-12. Currently, I have to implement the JsonSchema trait instead, because the schema_name() function determines the key used for $defs.

Context

I'm working through canonicalizing the JSON Schemas for my project, and I noticed a minor difficulty in that process. I'm using the alpha.15 release.

The two main reasons we're using the alpha release are to generate 2020-12 schemas and to leverage the simplicity of the extend attribute. For 2020-12 schemas, schema bundling has been formalized. Of particular note:

1. "Any schema which provides a value for $id is considered a Schema Resource.
2. When resolving references to external schemas for bundling, the key for that external schema in the $defs section of the schema should be the $id of the referenced schema.

Consider the following example schema:

{
  "$id": "https://example.com/schemas/v1/foo.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bar": { "$ref": "/schemas/v1/bar.json" },
    "baz": { "$ref": "/schemas/v1/baz.json" },
  }
}

When resolved for bundling, this should then be:

{
  "$id": "https://example.com/schemas/v1/foo.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bar": { "$ref": "/schemas/v1/bar.json" },
    "baz": { "$ref": "/schemas/v1/baz.json" },
  },
  "$defs": {
    "https://example.com/schemas/v1/bar.json": {
      "$id": "https://example.com/schemas/v1/bar.json",
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      // definition of the actual schema
    },
    "https://example.com/schemas/v1/baz.json": {
      "$id": "https://example.com/schemas/v1/baz.json",
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      // definition of the actual schema
    }
  }
}

However, given the following rust code:

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[schemars(
  title = t!("schemas.foo.title").to_string(),
  description = t!("schemas.foo.description").to_string(),
  extend("$id" = "https://example.com/schemas/v1/foo.json")
)]
pub struct Foo {
  pub bar: Bar,
  pub baz: Baz,
}

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[schemars(
  title = t!("schemas.bar.title").to_string(),
  description = t!("schemas.bar.description").to_string(),
  extend("$id" = "https://example.com/schemas/v1/bar.json")
)]
pub struct Bar(pub int)

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[schemars(
  title = t!("schemas.baz.title").to_string(),
  description = t!("schemas.baz.description").to_string(),
  extend("$id" = "https://example.com/schemas/v1/baz.json")
)]
pub struct Baz(pub bool)

The output schema defines the referenced schemas in $defs as Bar and Baz - and there doesn't seem to be any way to change this behavior, short of writing a transform function to canonicalize referenced definitions or implementing the trait to have schema_name() return the $id value.

In my particular case, I have several separate schemas across multiple crates that need to reference schemas that are from logical, user, and integrator perspectives external to any given root schema being examined - so when I publish the canonical schemas, I want to be able to publish them both as general JSON schemas that reference external schemas and as conveniently bundled schemas.

Proposals

I can think of a few options, but am not savvy enough about the underlying implementation to be able to determine if they're good or which one is most maintainable. I lean towards recommending both of the following:

1. Add an attribute like defs_key to determine the string that should be used when adding the referenced schema to $defs.
2. Check whether a schema defines the $id keyword and, if so, always use that as the key for that schema's entry in $defs (or make this a generator option).

Separately (and I can create a separate issue for this if needed), it would be useful to be able to specify overrides for the value of schema_name() and schema_id() when deriving schemas.