From 1852d41f08b987ed900cfd411fa4b26968107991 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Fri, 19 Jan 2024 14:49:20 +0000 Subject: [PATCH 1/5] feat(cli/validate): add documentation around --extra-schema --- cli/commands/validate.mdx | 55 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/cli/commands/validate.mdx b/cli/commands/validate.mdx index 7f7d86c..7411519 100644 --- a/cli/commands/validate.mdx +++ b/cli/commands/validate.mdx @@ -10,11 +10,66 @@ flipt validate [flags] ### Options ``` + -e, --extra-schema string path to extra schema constraints -F, --format string output format: json, text (default "text") -h, --help help for validate --issue-exit-code int Exit code to use when issues are found (default 1) ``` +### Behavior + +This command validates Flipt's declarative feature configuration files. +It looks for features flag definitions in the same way as Flipts declarative backends. +Checkout the documentation on [locating flag state](/configuration/storage#locating-flag-state) to learn more about this process. + +### Extra Schema + +The flag `--extra-schema` (short form `-e`) can be used to pass additional constraints via a CUE schema file. +This file will be unified with the base schema used within `flipt validate` to ensure the format of Flipt files. +You can find the base schema [here](https://github.com/flipt-io/flipt/blob/main/internal/cue/flipt.cue). + +As an example, take the following flipt `features.yaml` file: + +```yaml +flags: +- key: someFeature + name: Some Feature +``` + +Running validate will succeed when provided with a path to this file. + +```console +➜ flipt validate +➜ echo $? +0 +``` + +By default, the flag `description` field is not required. However, imagine that you want to ensure this field is always provided with a non-empty string. You can do this via the `--extra-schema` flag and a CUE definition. +In this instance we're going to create a CUE file named `extended.cue`. +Within this file we will add a constraint to the `#Flag` CUE definition, which ensures our desired behavior. + +```cue +#Flag: { + description: =~"^.+$" +} +``` + +This definition ensures that description is both supplied and that the value matches the regular expression. +The regular expression in this example ensures a string with a length of at-least 1 character. + +Now when invoking the validate subcommand, we pass the path to this extra CUE definition: + +```console +➜ flipt validate -e extended.cue +Validation failed! + +- Message : flags.0.description: incomplete value =~"^.+$" + File : features.yaml + Line : 2 +``` + +Here we see that our additional constraint on description is being validated and described in the output. + ### More Info See the [flag state](/configuration/storage#flag-state-configuration) section of the documentation for more information. From 2988fc912f9a97f02df1032ce8aeac3880d4d859 Mon Sep 17 00:00:00 2001 From: GeorgeMac Date: Fri, 19 Jan 2024 14:50:31 +0000 Subject: [PATCH 2/5] chore: format code --- cli/commands/validate.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cli/commands/validate.mdx b/cli/commands/validate.mdx index 7411519..f645f53 100644 --- a/cli/commands/validate.mdx +++ b/cli/commands/validate.mdx @@ -32,8 +32,8 @@ As an example, take the following flipt `features.yaml` file: ```yaml flags: -- key: someFeature - name: Some Feature + - key: someFeature + name: Some Feature ``` Running validate will succeed when provided with a path to this file. From f17fa6a75b9a716df210b1077e1241acfad3832a Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Fri, 19 Jan 2024 14:51:42 +0000 Subject: [PATCH 3/5] chore(cli/validate): fix spelling mistakes --- cli/commands/validate.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cli/commands/validate.mdx b/cli/commands/validate.mdx index 7411519..c17b3a9 100644 --- a/cli/commands/validate.mdx +++ b/cli/commands/validate.mdx @@ -19,7 +19,7 @@ flipt validate [flags] ### Behavior This command validates Flipt's declarative feature configuration files. -It looks for features flag definitions in the same way as Flipts declarative backends. +It looks for features flag definitions in the same way as Flipt's declarative backends. Checkout the documentation on [locating flag state](/configuration/storage#locating-flag-state) to learn more about this process. ### Extra Schema @@ -57,7 +57,7 @@ Within this file we will add a constraint to the `#Flag` CUE definition, which e This definition ensures that description is both supplied and that the value matches the regular expression. The regular expression in this example ensures a string with a length of at-least 1 character. -Now when invoking the validate subcommand, we pass the path to this extra CUE definition: +Now when invoking the validate sub-command, we pass the path to this extra CUE definition: ```console ➜ flipt validate -e extended.cue From 7d6b5e0e72566eceea3f3dbeb026141c6ea8236d Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Tue, 23 Jan 2024 09:41:10 -0500 Subject: [PATCH 4/5] chore: Update cli/commands/validate.mdx --- cli/commands/validate.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli/commands/validate.mdx b/cli/commands/validate.mdx index a52860d..3fc1649 100644 --- a/cli/commands/validate.mdx +++ b/cli/commands/validate.mdx @@ -55,7 +55,7 @@ Within this file we will add a constraint to the `#Flag` CUE definition, which e ``` This definition ensures that description is both supplied and that the value matches the regular expression. -The regular expression in this example ensures a string with a length of at-least 1 character. +The regular expression in this example ensures a string with a length of at least 1 character. Now when invoking the validate sub-command, we pass the path to this extra CUE definition: From 0ac70eee2b3f8790b6c72ba5e89ef5ad59d9d3af Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Tue, 23 Jan 2024 09:43:12 -0500 Subject: [PATCH 5/5] chore: add link to cue --- cli/commands/validate.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cli/commands/validate.mdx b/cli/commands/validate.mdx index 3fc1649..4386492 100644 --- a/cli/commands/validate.mdx +++ b/cli/commands/validate.mdx @@ -19,12 +19,12 @@ flipt validate [flags] ### Behavior This command validates Flipt's declarative feature configuration files. -It looks for features flag definitions in the same way as Flipt's declarative backends. -Checkout the documentation on [locating flag state](/configuration/storage#locating-flag-state) to learn more about this process. + +It looks for features flag definitions in the same way as Flipt's declarative backends. Checkout the documentation on [locating flag state](/configuration/storage#locating-flag-state) to learn more about this process. ### Extra Schema -The flag `--extra-schema` (short form `-e`) can be used to pass additional constraints via a CUE schema file. +The flag `--extra-schema` (short form `-e`) can be used to pass additional constraints via a [CUE](https://cuelang.org/) schema file. This file will be unified with the base schema used within `flipt validate` to ensure the format of Flipt files. You can find the base schema [here](https://github.com/flipt-io/flipt/blob/main/internal/cue/flipt.cue).