can't provide field-specific descriptions of object types

[cdmistman]

I'm trying to use a json schema using this go module to create a JSON schema for toml LSP provision using taplo. As such, I'm looking to make descriptions that are as useful as possible.

i have a type Command which is used often in the schema. in toml, a field of this type may be written as any of:

asString = "echo this is a command as a string"
asArray = ["echo", "this", "is", "an", "array"]

[asObject]
command = ["echo", "this must be an array"]
env = { this = "env var object is optional" }

the internal implementation looks something like (note i've configured jsonschema to use toml name declarations)

type FileConfig struct {
  onRun Command `toml:"onRun"`
  onStart Command `toml:"onStart"`
}

type Command struct {
  SysCommand
}

type SysCommand struct {
  command []string `toml:"command"`
  env map[string]string `toml:"env"`
}

func (c *Command) UnmarshalTOML(data interface{}) error {
  // implements the logic of generating the SysCommand using any of the 3 types string, array of strings, or table as described above
}

func (c Command) JSONSchema(s *jsonschema.Schema) {
  // creates an anyOf jsonschema type, options are string, array of string, and the generated schema of SysCommand
  // also sets Description to provide useful information about the 3 types
}

now, i'd like to provide additional documentation about onRun and onCommand. note that this is not possible using jsonschema_description in the field tag (and even if it did, it wouldn't help me in this situation, as i still want the description from the Command type). In order to accomplish this, I tried to do a little refactoring (looking at only onRun):

type FileConfig struct {
  onRun OnRunCommand `toml:"onRun"`
  // leave other fields alone for now
}

type OnRunCommand struct {
  Command
}

function (c OnRunCommand) JSONSchemaExtend(s *jsonschema.Schema) {
  fmt.Println("hello")
  s.Description = "Command to run when we want to Run.\n\n" + s.Description
}

However, this doesn't work - hello is never printed. As it turns out, if a type has JSONSchema (even if it's implemented on the embedded struct), JSONSchemaExtend is never called. I think this pattern is especially useful for this scenario, as taplo doesn't use the description field of an object field which has $ref

[samlown]

Hi @cdmistman! Okay, I see what you mean, but I'm not sure if a fix is possible as this feature depends on the underlying implementation of Go. If there is a JSONSchema method there, it will prevent automated generation. Could you not use the JSONSchemaExtend method in the Command struct instead of the override?

[cdmistman]

the problem i was working with was adding specifics to descriptions dependent on context. as mentioned, i'm using this schema in taplo which doesn't respect descriptions on fields of complex types. for example, foo's bar doesn't appear with taplo (not testing this in a schema at all, purely by memory):

{
  "foo": {
    "type": "object",
    "properties": {
      "bar": {
        "$ref": "#/$defs/bar",
        "description": "foo's bar"
      }
    }
  },
  "bar": {
    "description": "a bar",
    "type": "object"
  }
}

it's been a while since i dug through the source code here, but iirc the schema generation doesn't call JSONSchemaExtend if there's a JSONSchema. I think if you support JSONSchemaExtend for schemas that were generated with JSONSchema then that should support this use-case