API: GetSchemaType/GetSchemaTypeMapping export the overall informations about property doc, default value, readonly, ...

[amyXia1994]

The GetSchemaType and GetSchemaTypeMapping API now export schema Type in following structure:

message KclType {
	string type = 1;                     // schema, dict, list, str, int, float, bool, null, type_string
	repeated KclType union_types = 2 ;   // union types
	string default = 3;                  // default value

	string schema_name = 4;              // schema name
	string schema_doc = 5;               // schema doc
	map<string, KclType> properties = 6; // schema properties
	repeated string required = 7;        // required schema properties, [property_name1, property_name2]

	KclType key = 8;                     // dict key type
	KclType item = 9;                    // dict/list item type

	int32 line = 10;

	repeated Decorator decorators = 11;  // schema decorators
}

Following information of the schema are not covered:

1. the description of each property
2. the examples of the schema
3. the file path of the schema

see schema object in openapi: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object

[amyXia1994]

bug report:

• The result of KclvmService.GetSchemaType API contains mistakes: the required values in KclType #629

[Peefy]

With the implementation of KCL rust doc parser, these field implementations have become feasible and can be added to the API while maintaining compatibility.

[Peefy]

The new API is here @amyXia1994

message KclType {
	string type = 1;                     // schema, dict, list, str, int, float, bool, null, type_string
	repeated KclType union_types = 2 ;   // union types
	string default = 3;                  // default value
	string schema_name = 4;              // schema name
	string schema_doc = 5;               // schema doc
	map<string, KclType> properties = 6; // schema properties
	repeated string required = 7;        // required schema properties, [property_name1, property_name2]
	KclType key = 8;                     // dict key type
	KclType item = 9;                    // dict/list item type
	int32 line = 10;
	repeated Decorator decorators = 11;  // schema decorators

	string filename = 12;                // filename represents the absolute path of the file name where the attribute is located.
	string pkg_path = 13;                // pkg_path represents the path name of the package where the attribute is located.
	string description = 14;             // description represents the document of the attribute.
	map<string, Example> examples = 15;  // A map object to hold examples, the key is the example name.
}

message Decorator {
	string name = 1;
	repeated string arguments = 2;
	map<string, string> keywords = 3;
}

message Example {
	string summary = 1;                // Short description for the example.
	string description = 2;            // Long description for the example.
	google.protobuf.Any value = 3;     // Embedded literal example.
}

[amyXia1994]

@Peefy good job!

I think the doc for each Property is still missing. The schema_doc field only covers the doc of the property type when the property type is schema, but does not cover the doc of the property. In OpenAPI, if nested models are explicitly declared, a $ref field can be used along with description to allow the schema type to be defined in a deeper level of nesting. ref: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object I saw you've add the description to message KclType 👍

And I might have missed some other necessary fields in the KclType model in the original issue:

• parent schema of the current schema
• schema parameters if exist
• the protocol that validates the current schema if exists (ref: https://kcl-lang.io/docs/reference/lang/tour/#advanced)
• ..., maybe more, we can complete this API continuously

Furthermore, if we support generating docs for other "types" of models, such as mixin, protocol, and rule, This API might need some refactoring. Since the spec of all those models might be different, perhaps a new "KCLType" which wraps all those models is needed?