From c53cb45db5c472d52b3bd24d62ac8a1e0489ce88 Mon Sep 17 00:00:00 2001 From: John Ryan Date: Wed, 12 Jan 2022 09:52:08 -0800 Subject: [PATCH] Inception (incomplete) --- proposals/ytt/004-schema-validation/README.md | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 proposals/ytt/004-schema-validation/README.md diff --git a/proposals/ytt/004-schema-validation/README.md b/proposals/ytt/004-schema-validation/README.md new file mode 100644 index 000000000..69cccf4ea --- /dev/null +++ b/proposals/ytt/004-schema-validation/README.md @@ -0,0 +1,194 @@ +--- +title: "Schema Validation" +authors: [ "John S. Ryan " ] +status: "draft" +approvers: [] +--- + +# Schema Validations + +## Problem Statement + +## Terminology / Concepts +_Define any terms or concepts that are used throughout this proposal._ + +## Proposal + + +### Specification / Use Cases + +- [Use Case: Required Input](#use-case-required-input) + - [Required input for values with length](#required-input-for-types-with-length) + - [Required input for types with empty value](#required-input-for-types-with-empty-value) + - [Required input for types with no empty value](#required-input-for-types-with-no-empty-value) +- [Use Case: Enumeration](#use-case-enumeration) +- [Use Case: Union Structures](#use-case-union-structures) + +#### Use Case: Required Input + +When the author cannot/will not provide a default value for a data value and requires the consumer to provide it. + +Where possible, authors are encouraged to use a type-specific "non-empty" validation. As a fallback, they may opt for nullable+not_null. + +##### Required input for types with length + +**String Values** + +Data values of type `string` carry an automatic non-empty validation: + +```yaml +#@data/values-schema +--- +dex: + #@schema/validate min_len=1 + namespace: "" +``` +is identical to + +```yaml +#@data/values-schema +--- +dex: + namespace: "" +``` + +The violation should be worded to convey needing a non-empty value: + +> A value for "namespace" is required; it is empty. + +**Array Values** + +Similarly, a non-empty value of an array is having at least one element: + +```yaml +#@data/values-schema +--- +dex: + oauth2: + #@schema/validate min_len=1 + responseTypes: + - "" +``` + +Violation error message: + +> A value for "responseTypes" is required; it is empty. + +##### Required input for types with empty value + +##### Required input for types with no empty value + +Some types have no natural (or easily detectable) "empty" value. In these cases, authors mark the value as "nullable" and constraint it to be "not null": + +```yaml +#@data/values-schema +--- +dex: + #@schema/nullable + #@schema/validate not_null=True + someMap: +``` + +Which may be common enough to warrant some syntactic sugar: + +```yaml +#@data/values-schema +--- +dex: + #@schema/unset + someMap: +``` + +#### Use Case: Enumeration + +It's quite common for string values to be constrained to a finite set: an enumeration. + +``` +data.values.dex.config.connector in ("oidc", "ldap") or \ + assert.fail("Dex connector should be oidc or ldap") +``` + +```yaml +#@data/values-schema +--- +dex: + config: + #@schema/validate enum=["oidc", "ldap"] + connector: "" +``` + + +#### Use Case: Union Structures + +Sometimes, design data values where two (or more) sibling keys are intended to be mutually exclusive. That is: it is invalid for more than one of the siblings to be non-null. + +For example: +```yaml +#@data/values +--- +dex: + config: + oidc: + CLIENT_ID: null #! required if oidc enabled + CLIENT_SECRET: null #! required if oidc enabled + issuer: null #! is required if oidc enabled + ldap: + host: null #! is required if ldap enabed + bindDN: null + bindPW: null +``` + +Only one authorization+authentication scheme can be active at a time. + +```yaml +#@data/values-schema +--- +dex: + #@overlay/match by=overlay.one_of(["oidc", "ldap"]) + #@schema/validate + config: + #@schema/nullable + oidc: + CLIENT_ID: null #! required if oidc enabled + CLIENT_SECRET: null #! required if oidc enabled + issuer: null #! is required if oidc enabled + #@schema/nullable + ldap: + host: null #! is required if ldap enabed + bindDN: null + bindPW: null +``` + + +#### Consideration: Order of Validations + +> I want to be able to affect the order in which violations are reported +> So that the user’s attention goes to the violations that have the most impact on how the invocation runs. + +#### Consideration: Merging Schema Nodes + + + +### Other Approaches Considered + + +## Open Questions + + +## Answered Questions + + +## Complete Examples + +- https://github.com/vmware-tanzu/community-edition/tree/main/addons/packages + - https://github.com/vmware-tanzu/community-edition/blob/cc7eb24b0e13875a06ac8578cd73f83a217ec4d9/addons/packages/harbor/2.2.3/bundle/config/values.star + - https://github.com/vmware-tanzu/community-edition/blob/cc7eb24b0e13875a06ac8578cd73f83a217ec4d9/addons/packages/vsphere-cpi/1.22.4/bundle/config/values.star + - https://github.com/vmware-tanzu/community-edition/blob/cc7eb24b0e13875a06ac8578cd73f83a217ec4d9/addons/packages/velero/1.6.3/bundle/config/values.star + - https://github.com/vmware-tanzu/community-edition/blob/cc7eb24b0e13875a06ac8578cd73f83a217ec4d9/addons/packages/pinniped/0.12.0/bundle/config/upstream/_ytt_lib/supervisor/helpers.lib.yaml +- https://github.com/vmware-tanzu/tanzu-framework + - https://github.com/vmware-tanzu/tanzu-framework/blob/2b3c557f5651a0bfe79dac1b19e12d5925178bef/pkg/v1/providers/ytt/lib/validate.star + - e.g. `validate_configuration()` used by https://github.com/vrabbi/tkg-resources/blob/0e302afc87997bee8312cc7da25b76815ea01b0c/TKG%20Customization/tkg/providers/infrastructure-vsphere/v0.7.1/ytt/overlay.yaml +- https://github.com/cloudfoundry/cf-for-k8s/blob/develop/config/get_missing_parameters.star + +### +