kubevela.github.io/versioned_docs/version-v0.3.5/platform-builder-guide/using-cue/openapi-v3-json-schema.md

title
Auto-generated Schema

Auto-generated OpenAPI v3 JSON Schema for Capability

For any installed capability, KubeVela will automatically generate OpenAPI v3 JSON Schema for it.

Why?

In definition objects, parameter section are expected to be set by developers when creating Application object. While there is another GUI way for developers to input all parameter fields by rendering parameter section to OpenAPI v3 Specification.

For example, after you created a definition object, KubeVela will generate OpenAPI v3 JSON Schema from parameter of Workload Type webservice.

{
	"properties": {
		"cmd": {
			"description": "Commands to run in the container",
			"items": {
				"type": "string"
			},
			"title": "cmd",
			"type": "array"
		},
		"cpu": {
			"description": "Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)",
			"title": "cpu",
			"type": "string"
		},
		"env": {
			"description": "Define arguments by using environment variables",
			"items": {
				"properties": {
					"name": {
						"description": "Environment variable name",
						"title": "name",
						"type": "string"
					},
					"value": {
						"description": "The value of the environment variable",
						"title": "value",
						"type": "string"
					},
					"valueFrom": {
						"description": "Specifies a source the value of this var should come from",
						"properties": {
							"secretKeyRef": {
								"description": "Selects a key of a secret in the pod's namespace",
								"properties": {
									"key": {
										"description": "The key of the secret to select from. Must be a valid secret key",
										"title": "key",
										"type": "string"
									},
									"name": {
										"description": "The name of the secret in the pod's namespace to select from",
										"title": "name",
										"type": "string"
									}
								},
								"required": ["name", "key"],
								"title": "secretKeyRef",
								"type": "object"
							}
						},
						"required": ["secretKeyRef"],
						"title": "valueFrom",
						"type": "object"
					}
				},
				"required": ["name"],
				"type": "object"
			},
			"title": "env",
			"type": "array"
		},
		"image": {
			"description": "Which image would you like to use for your service",
			"title": "image",
			"type": "string"
		},
		"port": {
			"default": 80,
			"description": "Which port do you want customer traffic sent to",
			"title": "port",
			"type": "integer"
		}
	},
	"required": ["image", "port"],
	"type": "object"
}

You can render the schema by form-render or React JSON Schema form. A web form can be as below.

How to use the generated JSON Schema of definition

When a platform builder applies a WorkloadDefinition or TraitDefinition, a ConfigMap will be created in a namespace same as the definition (by default it will be in vela-system namespace) and labeled with definition.oam.dev=schema.

$ kubectl get cm -n vela-system -l definition.oam.dev=schema
NAME                DATA   AGE
schema-ingress      1      19s
schema-scaler       1      19s
schema-task         1      19s
schema-webservice   1      19s
schema-worker       1      20s

The ConfigMap name is in the format schema-$definitionName, and the key of ConfigMap data is openapi-v3-json-schema. For example, we can use the following command to get the JSON Schema of webservice.

$ kubectl get cm schema-webservice -n vela-system -o yaml
apiVersion: v1
data:
  openapi-v3-json-schema: '{"properties":{"cmd":{"description":"Commands to run in
    the container","items":{"type":"string"},"title":"cmd","type":"array"},"cpu":{"description":"Number
    of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)","title":"cpu","type":"string"},"env":{"description":"Define
    arguments by using environment variables","items":{"properties":{"name":{"description":"Environment
    variable name","title":"name","type":"string"},"value":{"description":"The value
    of the environment variable","title":"value","type":"string"},"valueFrom":{"description":"Specifies
    a source the value of this var should come from","properties":{"secretKeyRef":{"description":"Selects
    a key of a secret in the pod''s namespace","properties":{"key":{"description":"The
    key of the secret to select from. Must be a valid secret key","title":"key","type":"string"},"name":{"description":"The
    name of the secret in the pod''s namespace to select from","title":"name","type":"string"}},"required":["name","key"],"title":"secretKeyRef","type":"object"}},"required":["secretKeyRef"],"title":"valueFrom","type":"object"}},"required":["name"],"type":"object"},"title":"env","type":"array"},"image":{"description":"Which
    image would you like to use for your service","title":"image","type":"string"},"port":{"default":80,"description":"Which
    port do you want customer traffic sent to","title":"port","type":"integer"}},"required":["image","port"],"type":"object"}'
kind: ConfigMap
metadata:
  name: schema-webservice
  namespace: vela-system

If you adopt KubeVela API Server, you can get the schema by API /api/definitions/{definitionName}.