Interception occurs before PrepareJSONSchema

[twelvelabs]

Describe the bug

I would like my schema to include markdownDescription attributes so that VS Code (via the JSON and YAML language servers) will render help text properly in hover overlays. Since I don't want to have to maintain duplicate versions of each description, I was hoping to use InterceptSchema to populate the markdownDescription value automatically.

Unfortunately, many of my descriptions are set via PrepareJSONSchema() (they're long and not conducive to being managed in struct tags). It appears that both the property and schema interceptors are called before PrepareJSONSchema.

To Reproduce

type MySchema struct {
	Something string `yaml:"something"`
}

func (m *MySchema) PrepareJSONSchema(schema *jsonschema.Schema) error {
	schema.Properties["something"].TypeObject.WithDescription(`
		Super long description...
	`)
}

schema, err := (&jsonschema.Reflector{}).Reflect(
	&MySchema{},
	jsonschema.InterceptSchema(func(params jsonschema.InterceptSchemaParams) (bool, error) {
		if params.Processed {
			params.Schema.WithExtraPropertiesItem(
				"markdownDescription", *params.Schema.Description,
			)
		}
		return false, nil
	}),
)

Expected behavior

I expected schema to contain the markdownDescription prop set to the content of the description... sadly, it did not. I had to post-process schema with the following. Which honestly, wasn't that big of a deal. It was just confusing because it seemed like the interceptor approach was the right way to go about it.

func setMarkdownDescription(schema *jsonschema.Schema) {
	if schema.Description != nil {
		schema.WithExtraPropertiesItem(
			"markdownDescription", *schema.Description,
		)
	}
	for _, s := range schema.Properties {
		if s.TypeObject != nil {
			setMarkdownDescription(s.TypeObject)
		}
	}
	for _, s := range schema.Definitions {
		if s.TypeObject != nil {
			setMarkdownDescription(s.TypeObject)
		}
	}
}

Additional context

I don't know if this is technically a bug, or if the behavior is by design. If it's the latter, I think it would be good to document in both interceptor functions to prevent further confusion.