How to Generate a JSON Schema for a Method?

[damo]

I need to generate a JSON schema that describes a Java method and its parameters. This is not much different from describing a Java class and its fields, but I'm not sure if it is possible to do this using the schema generator.

For context, my goal is to generate schemas from methods to match the requirements of OpenAI function calling. A JSON schema describes a function and its parameters and the AI model may request execution of that function by returning JSON—conforming to the schema—that represents the parameter values to pass to that function. The result of the invocation is then passed back to the AI model.

I was thinking that maybe I could implement a java.lang.reflect.Type to represent a method as if it were a class, but that feels like it might hit a road block if the generator expect to see a Class object at some point. Another possibility is to generate schemas for each of the typed parameters and then combine those schemas into one, but then I'd need to deal with moving $schema properties, consolidating the $defs, and rewriting all the $ref fields—i.e., more work that I'd like. Does anyone have any other suggestions?

[CarstenWickner]

HI @damo,

That sounds more like a job for OpenAPI/Swagger than for JSON Schema.

While the JSON Schema Generator is capable of documenting methods, it does not explicitly document the expected input parameters. By excluding the Option.SCHEMA_VERSION_INDICATOR, you also don't have to move around any $schema properties.
For example, the following piece of code

SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.JAVA_OBJECT);
SchemaGenerator generator = new SchemaGenerator(configBuilder.build());
ObjectNode schema = generator.generateSchema(Example.class);

considering this target type:

interface Example {
    Example getSelf();
    String methodWithStringResult(Integer paramOne, List<String> paramTwo);
    void someVoidMethod(String parameter);
}

results in this schema being generated:

{
  "type" : "object",
  "properties" : {
    "getSelf()" : {
      "$ref" : "#"
    },
    "methodWithStringResult(Integer, List<String>)" : {
      "type" : "string"
    },
    "someVoidMethod(String)" : false
  }
}

Again, you want to document the inputs, so the OpenAPI approach to describing web service endpoints seems more suitable for your goal, or something similar, e.g., a WSDL.

EDIT: After further looking into it, I created an example: #526
Is this the kind of result you're after?
https://github.com/victools/jsonschema-generator/pull/526/files#diff-213d03be65c7e496965f59fddca25a59cb808d18014f538476f89375e699d641

[damo]

Thanks @CarstenWickner,

I have been leaning more towards using classes and their fields to model an OpenAI function call, rather than a method. Your example is similar to what I have been thinking of doing, so seeing it in action is very helpful and brings some clarity to the matter. I think I'll go with something like you suggest.

Thanks, again.