pyrox.dev
1# Cue (Cuelang) {#cuelang}
2
3[Cuelang](https://cuelang.org/) is a language to:
4
5- describe schemas and validate backward-compatibility
6- generate code and schemas in various formats (e.g. JSON Schema, OpenAPI)
7- do configuration akin to [Dhall Lang](https://dhall-lang.org/)
8- perform data validation
9
10## Cuelang schema quick start {#cuelang-quickstart}
11
12Cuelang schemas are similar to JSON, here is a quick cheatsheet:
13
14- Default types includes: `null`, `string`, `bool`, `bytes`, `number`, `int`, `float`, lists as `[...T]` where `T` is a type.
15- All structures, defined by: `myStructName: { <fields> }` are **open** -- they accept fields which are not specified.
16- Closed structures can be built by doing `myStructName: close({ <fields> })` -- they are strict in what they accept.
17- `#X` are **definitions**, referenced definitions are **recursively closed**, i.e. all its children structures are **closed**.
18- `&` operator is the [unification operator](https://cuelang.org/docs/references/spec/#unification) (similar to a type-level merging operator), `|` is the [disjunction operator](https://cuelang.org/docs/references/spec/#disjunction) (similar to a type-level union operator).
19- Values **are** types, i.e. `myStruct: { a: 3 }` is a valid type definition that only allows `3` as value.
20
21- Read <https://cuelang.org/docs/concepts/logic/> to learn more about the semantics.
22- Read <https://cuelang.org/docs/references/spec/> to learn about the language specification.
23
24## `writeCueValidator` {#cuelang-writeCueValidator}
25
26Nixpkgs provides a `pkgs.writeCueValidator` helper, which will write a validation script based on the provided Cuelang schema.
27
28Here is an example:
29```nix
30pkgs.writeCueValidator (pkgs.writeText "schema.cue" ''
31 #Def1: {
32 field1: string
33 }
34'') { document = "#Def1"; }
35```
36
37- The first parameter is the Cue schema file.
38- The second parameter is an options parameter, currently, only: `document` can be passed.
39
40`document` : match your input data against this fragment of structure or definition, e.g. you may use the same schema file but different documents based on the data you are validating.
41
42Another example, given the following `validator.nix` :
43```nix
44{
45 pkgs ? import <nixpkgs> { },
46}:
47let
48 genericValidator =
49 version:
50 pkgs.writeCueValidator (pkgs.writeText "schema.cue" ''
51 #Version1: {
52 field1: string
53 }
54 #Version2: #Version1 & {
55 field1: "unused"
56 }'') { document = "#Version${toString version}"; };
57in
58{
59 validateV1 = genericValidator 1;
60 validateV2 = genericValidator 2;
61}
62```
63
64The result is a script that will validate the file you pass as the first argument against the schema you provided `writeCueValidator`.
65
66It can be any format that `cue vet` supports, i.e. YAML or JSON for example.
67
68Here is an example, named `example.json`, given the following JSON:
69```
70{ "field1": "abc" }
71```
72
73You can run the result script (named `validate`) as the following:
74
75```console
76$ nix-build validator.nix
77$ ./result example.json
78$ ./result-2 example.json
79field1: conflicting values "unused" and "abc":
80 ./example.json:1:13
81 ../../../../../../nix/store/v64dzx3vr3glpk0cq4hzmh450lrwh6sg-schema.cue:5:11
82$ sed -i 's/"abc"/3/' example.json
83$ ./result example.json
84field1: conflicting values 3 and string (mismatched types int and string):
85 ./example.json:1:13
86 ../../../../../../nix/store/v64dzx3vr3glpk0cq4hzmh450lrwh6sg-schema.cue:5:11
87```
88
89**Known limitations**
90
91* The script will enforce **concrete** values and will not accept lossy transformations (strictness). You can add these options if you need them.