JSON schema property with both `$ref` and `description` incorrectly resolves and does not show description

[uncenter]

I recently made a change for the SchemaStore Cargo.toml schema that added support for [lints]/[workspace.lints]. For workspace.lints specifically, this looks like:

"lints": {
  "$ref": "#/definitions/Lints",
  "description": "The `workspace.lints` table is where you define lint configuration to be inherited by members of a workspace.",
  "x-taplo": {
    "links": {
      "key": "https://doc.rust-lang.org/cargo/reference/workspaces.html#the-workspace-section"
    }
  }
},

(https://github.com/SchemaStore/schemastore/blob/7c91a8e5a643d68cd11ce7ebcd18214a88d1cf7e/src/schemas/json/cargo.json#L1185-L1193)

You can see that both $ref and description are defined for this property. However, when using the Taplo LSP/extension in VS Code (and presumably in other editors), hovering over the lints part of workspace.lints shows no information/tooltip:

When applying the same schema in a JSON file with the same contents, hovering over the lints property of workspace.lints does show a tooltip:

Contents of the two files for reference

{
	"$schema": "https://json.schemastore.org/cargo.json",
	"workspace": {
		"lints": {
			"clippy": {
				"missing_errors_doc": "allow",
				"all": {
					"level": "warn",
					"priority": -1
				},
				"pedantic": {
					"level": "warn",
					"priority": -1
				}
			}
		}
	}
}

"$schema" = "https://json.schemastore.org/cargo.json"

[workspace.lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }
missing_errors_doc = "allow"

I suspect this is an issue where when resolving the $ref, the description field is ignored.

I can confirm that the definition on hover works in general with the TOML file, as evidenced by the tooltip shown if I hover over the clippy property of workspace.lints:

And of course this still works for the JSON file:

[uncenter]

This might be an issue with https://github.com/Stranger6667/jsonschema, not sure exactly where the responsibility for this comes from. Happy to remake this over there if this is the case.

[uncenter]

I'm now wondering if this is of my own fault. It is more likely that the behavior I expect is simply not how JSON Schema itself works/is defined. In that case I can probably use something like https://github.com/orgs/json-schema-org/discussions/502 to move the reference out of the top level area for this property, but let me know if my schema snippet is invalid and I can close this :)

[uncenter]

@Stranger6667 do you know if this is a bug in Taplo/JSONSchema or simply not part of the spec for JSON Schema?

[Stranger6667]

@uncenter

I suspect this is an issue where when resolving the $ref, the description field is ignored.

JSON Schema drafts 7 and earlier ignore all other keywords if $ref is present in a schema. However, "description" is an annotation anyway and should be collected by jsonschema during the compilation of a validator (though I don't remember if the version used by taplo does collect it).

Then it depends on how it is propagated to the editor. My assumption is that it is not from the jsonschema side as it only does validation (I found only validate calls in taplo) without even touching the apply method that provides annotated validation results.

Therefore I think the issue is somewhere in taplo.