Introduce a new API within the openapi package to convert a Ballerina Type Symbol to a JSON Schema.

[MohamedSabthar]

Problem

The Ballerina agent package requires the generation of JSON Schema from Ballerina type symbols. The objective is to produce an expanded schema. For example, consider the following Ballerina record type Foo:

# Represents a Foo object.
type Foo record {|
    # Represents a Bar object with an integer value.
    Bar bar;
|};

# Represents a Bar object with an integer value.
type Bar record {|
    # The integer value. Must be between 0 and 100 (inclusive).
    int val;
|};

The generated schema should adhere to the following format:

{
  "description": "Represent a foo object",
  "type": "object",
  "properties": {
    "bar": {
      "description": "Represents a Bar object with an integer value.",
      "type": "object",
      "properties": {
        "val": {
          "type": "integer",
          "description": "The integer value. Must be between 0 and 100 (inclusive)."
        }
      },
      "required": ["val"]
    }
  },
  "required": ["bar"],
  "additionalProperties": false
}

Proposed Solution

A new native API may be introduced within the openapi package.

Alternatives

No response

Version

No response

[TharmiganK]

OpenAPI type mapper can be used for this purpose. But the schema we build is swagger schema which only utilizes specific fields from JSON schema specification and adds its own set of fields.

The swagger exposes an API to convert its schema to JSON schema. We can use that, but it might not be the accurate JSON schema representation since it only support specific JSON schema fields.

Ideally, we need a new implementation for type to JSON schema which can be provided by the jsondata package. The following spec we used for Ballerina to OpenAPI can be used as a starting point: https://github.com/ballerina-platform/openapi-tools/blob/master/docs/ballerina-to-oas/spec/spec.md. Since it will take some time for design and implementation, we will provide an API from openapi-tools.

cc: @MaryamZi @SasinduDilshara

Note: The API from the OpenAPI tool package will still have the limitation of the Ballerina to Schema generation. Refer the spec for the supported types and the corresponding schemas.

Also, the expand option is currently not available in the Type mapper component. We need to implement this.

[TharmiganK]

Planned to introduce the following API: TypeMapper:getJsonSchemaString

It takes the SyntaxNodeAnalysisContext from the ballerina compiler plugin and provides the JSON schema in string format:

Sample usage:

TypeMapper typeMapper = new TypeMapperImpl(context);
// Generation with expansion=true option
String jsonSchemaString = typeMapper.getJsonSchemaString(typeSymbol, true);

[lnash94]

Are we planning to implement and expose this API via the ballerina compiler plugin, or the ballerina-to-openAPI package?

[TharmiganK]

Are we planning to implement and expose this API via the ballerina compiler plugin, or the ballerina-to-openAPI package?

ballerina-to-openAPI package

[MaryamZi]

This OpenAPI-based approach works at compile/dev-time, right?

Ideally, we need a new implementation for type to JSON schema which can be provided by the jsondata package. The following spec we used for Ballerina to OpenAPI can be used as a starting point: https://github.com/ballerina-platform/openapi-tools/blob/master/docs/ballerina-to-oas/spec/spec.md. Since it will take some time for design and implementation, we will provide an API from openapi-tools.

cc: @MaryamZi @SasinduDilshara

In contrast, this schema generation would happen at runtime. Even if we do have a library function to do this, I believe we'll still need the compile/dev-time schema generation.

While we do require runtime schema generation for AI use-cases, I don't think this is a common use-case. We'll discuss this and get back. cc @gimantha