Skip to main content
Version: 0.4.5


Use KCL to Validate the Data

In addition to using KCL code to generate configuration formats such as JSON/YAML, KCL also supports format validation of JSON/YAML data. As a configuration language, KCL covers almost all features of OpenAPI.

In KCL, a structure definition can be used to validate configuration data. At the same time, it supports user-defined constraint rules through the check block, and writes validation expressions in the schema to check and validate the attributes defined by the schema. It is very clear and simple to check whether the input JSON/YAML satisfies the corresponding schema structure definition and constraints.


In the schema, we can use the check keyword to write the validation rules of every schema attribute. Each line in the check block corresponds to a conditional expression. When the condition is satisfied, the validation is successful. The conditional expression can be followed by , "check error message" to indicate the message to be displayed when the check fails. Here is an example of a schema with constraint expressions.

import regex

schema Sample:
foo: str # Required, cannot be None/Undefined, and the type must be str
bar: int # Required, cannot be None/Undefined, and the type must be int
fooList: [int] # Required, cannot be None/Undefined, and the type must be int list
color: "Red" | "Yellow" | "Blue" # Required, literal union type, and must be one of "Red", "Yellow", "Blue".
id?: int # Optional, can be None/Undefined, the type must be int

0 <= bar < 100 # bar must be greater than or equal to 0 and less than 100
0 < len(fooList) < 100 # fooList cannot be None/Undefined, and the length must be greater than 0 and less than 100
regex.match(foo, "^The.*Foo$") # regular expression matching
bar in range(100) # bar can only range from 1 to 99
bar in [2, 4, 6, 8] # bar can only take 2, 4, 6, 8
bar % 2 == 0 # bar must be a multiple of 2
all foo in fooList {
foo > 1
} # All elements in fooList must be greater than 1
any foo in fooList {
foo > 10
} # At least one element in fooList must be greater than 10
abs(id) > 10 if id # check expression with if guard, when id is not empty, the absolute value of id must be greater than 10

To sum up, the validation kinds supported in KCL schema are:

RangeUsing comparison operators such as <, >
RegexUsing methods such as match from the regex system module
LengthUsing the len built-in function to get the length of a variable of type list/dict/str
EnumUsing literal union types
Optional/RequiredUsing optional/required attributes of schema
ConditionUsing the check if conditional expression

How to use

There is a JSON format file data.json:

"name": "Alice",
"age": "18",
"message": "This is Alice",
"data": {
"id": "1",
"value": "value1"
"labels": {
"key": "value"
"hc": [1, 2, 3]

Build a validated KCL file schema.k:

schema User:
name: str
age: int
message?: str
data: Data
labels: {str:}
hc: [int]

age > 10

schema Data:
id: int
value: str

Execute the following command:

$ kcl-vet data.json schema.k
Validate succuss!

Based on this, KCL provides the corresponding Validation Tool to validate JSON/YAML data directly. In addition, based on this capability, we can build a K-V validation visualization product.

Future Plan

The improvement of KCL validation capabilities will gradually focus on the "static" aspect, that is, at compile time, combined with the ability of formal validation, it can directly analyze whether the data meets the constraints, whether the constraints conflict with each other, etc., and can be exposed in real-time through the IDE.

We also expect that KCL models and constraints can be managed as a package (this package has only KCL files). For example, the Kubernetes models and constraints can be used out of the box. Users can generate configurations or verify existing configurations, and can simply extend the models and constraints users want through KCL inheritance.