doc/languages-frameworks/cuelang.section.md

   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
  12 Cuelang 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
  26 Nixpkgs provides a `pkgs.writeCueValidator` helper, which will write a validation script based on the provided Cuelang schema.
  27
  28 Here is an example:
  29 ```nix
  30 pkgs.writeCueValidator
  31   (pkgs.writeText "schema.cue" ''
  32     #Def1: {
  33       field1: string
  34     }
  35   '')
  36   { document = "#Def1"; }
  37 ```
  38
  39 - The first parameter is the Cue schema file.
  40 - The second parameter is an options parameter, currently, only: `document` can be passed.
  41
  42 `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.
  43
  44 Another example, given the following `validator.nix` :
  45 ```nix
  46 { pkgs ? import <nixpkgs> {} }:
  47 let
  48   genericValidator = version:
  49   pkgs.writeCueValidator
  50     (pkgs.writeText "schema.cue" ''
  51       #Version1: {
  52         field1: string
  53       }
  54       #Version2: #Version1 & {
  55         field1: "unused"
  56       }''
  57     )
  58     { document = "#Version${toString version}"; };
  59 in
  60 {
  61   validateV1 = genericValidator 1;
  62   validateV2 = genericValidator 2;
  63 }
  64 ```
  65
  66 The result is a script that will validate the file you pass as the first argument against the schema you provided `writeCueValidator`.
  67
  68 It can be any format that `cue vet` supports, i.e. YAML or JSON for example.
  69
  70 Here is an example, named `example.json`, given the following JSON:
  71 ```
  72 { "field1": "abc" }
  73 ```
  74
  75 You can run the result script (named `validate`) as the following:
  76
  77 ```console
  78 $ nix-build validator.nix
  79 $ ./result example.json
  80 $ ./result-2 example.json
  81 field1: conflicting values "unused" and "abc":
  82     ./example.json:1:13
  83     ../../../../../../nix/store/v64dzx3vr3glpk0cq4hzmh450lrwh6sg-schema.cue:5:11
  84 $ sed -i 's/"abc"/3/' example.json
  85 $ ./result example.json
  86 field1: conflicting values 3 and string (mismatched types int and string):
  87     ./example.json:1:13
  88     ../../../../../../nix/store/v64dzx3vr3glpk0cq4hzmh450lrwh6sg-schema.cue:5:11
  89 ```
  90
  91 **Known limitations**
  92
  93 * The script will enforce **concrete** values and will not accept lossy transformations (strictness). You can add these options if you need them.