feat: add schema validation for variation value (#2760)

Author: cre8ivejp

ui/dashboard/package.json

@@ -43,6 +43,7 @@
     "@types/chart.js": "^4.0.1",
     "@types/js-cookie": "^3.0.6",
     "@types/react-date-range": "^1.4.10",
+    "ajv": "^8.20.0",
     "axios": "^1.18.1",
     "chart.js": "^4.5.1",
     "chartjs-adapter-luxon": "^1.3.1",
@@ -64,6 +65,7 @@
     "prettier": "^3.9.6",
     "prism-react-renderer": "^2.4.1",
     "query-string": "^9.4.1",
+    "re2js": "^2.8.6",
     "react": "^19.2.8",
     "react-chartjs-2": "^5.3.1",
     "react-date-range": "^2.0.1",

ui/dashboard/src/@locales/en/form.json

@@ -136,6 +136,35 @@
   "no-tags-found": "No tags were found in the selected environment",
   "placeholder-search": "Search",
   "feature-flags": {
+    "value-schema": {
+      "title": "Value Schema",
+      "tooltip": "Restrict which values this flag's variations can have. The available validators depend on the flag type:\nString: Enum or Regex\nNumber: Enum\nJSON: JSON Schema\nBoolean and YAML flags do not support value schemas.",
+      "no-schema": "No schema is defined. Variation values are accepted without validation.",
+      "has-schema": "Variation values are validated against this schema.",
+      "add": "Add Schema",
+      "edit": "Edit Schema",
+      "remove": "Remove Schema",
+      "add-title": "Add Value Schema",
+      "edit-title": "Edit Value Schema",
+      "type": "Schema Type",
+      "type-enum": "Enum",
+      "type-regex": "Regex",
+      "type-json-schema": "JSON Schema",
+      "enum-values": "Allowed Values",
+      "enum-values-placeholder": "Type a value and press enter",
+      "enum-values-number-note": "Each allowed value must be a number.",
+      "regex-pattern": "Pattern",
+      "regex-pattern-placeholder": "Enter a regular expression",
+      "regex-note": "The pattern is evaluated using Go regular expression syntax.",
+      "json-schema": "JSON Schema",
+      "json-schema-note": "Variation values are validated using JSON Schema draft 2020-12.",
+      "description-placeholder": "Explain the purpose of this schema (optional)",
+      "test": "Test against current variations",
+      "test-pass": "All variations match the schema.",
+      "test-fail": "{{count}} variation(s) do not match the schema.",
+      "test-valid": "Valid",
+      "test-invalid": "Invalid"
+    },
     "clone-title": "Clone Feature Flag",
     "clone-desc": "This will copy the targeting rules from the original flag to a new flag in the destination environment. The new flag will be created in a disabled state. Prerequisites, flag-based rules, and segment-based rules are not included.",
     "flag-id": "Flag ID",

ui/dashboard/src/@locales/en/message.json

@@ -3,6 +3,10 @@
   "validation": {
     "must-be-number": "This must be a number",
     "must-be-json": "This must be a JSON",
+    "value-schema-violation": "This value doesn't match the flag's value schema",
+    "value-schema-enum-not-number": "All allowed values must be numbers",
+    "value-schema-invalid-regex": "The pattern is not a valid RE2 regular expression",
+    "value-schema-invalid-json-schema": "The document is not a valid JSON Schema",
     "must-be-yaml": "This must be a YAML",
     "must-be-unique": "This must be unique",
     "max-length-number": "The maximum length for this field is {{count}} numbers.",

ui/dashboard/src/@locales/ja/form.json

@@ -135,6 +135,35 @@
   "no-tags-found": "選択した環境にタグが見つかりませんでした",
   "placeholder-search": "検索",
   "feature-flags": {
+    "value-schema": {
+      "title": "値スキーマ",
+      "tooltip": "このフラグのバリエーションに設定できる値を制限します。利用できるバリデーターはフラグの種類によって異なります:\n文字列: Enum または Regex\n数値: Enum\nJSON: JSONスキーマ\nブーリアンおよびYAMLフラグは値スキーマをサポートしていません。",
+      "no-schema": "スキーマが定義されていません。バリエーション値は検証なしで受け付けられます。",
+      "has-schema": "バリエーション値はこのスキーマに対して検証されます。",
+      "add": "スキーマを追加",
+      "edit": "スキーマを編集",
+      "remove": "スキーマを削除",
+      "add-title": "値スキーマを追加",
+      "edit-title": "値スキーマを編集",
+      "type": "スキーマタイプ",
+      "type-enum": "列挙型",
+      "type-regex": "正規表現",
+      "type-json-schema": "JSONスキーマ",
+      "enum-values": "許可される値",
+      "enum-values-placeholder": "値を入力してEnterキーを押してください",
+      "enum-values-number-note": "許可される値はすべて数値である必要があります。",
+      "regex-pattern": "パターン",
+      "regex-pattern-placeholder": "正規表現を入力",
+      "regex-note": "パターンはGoの正規表現構文で評価されます。",
+      "json-schema": "JSONスキーマ",
+      "json-schema-note": "バリエーション値はJSONスキーマ draft 2020-12で検証されます。",
+      "description-placeholder": "このスキーマの目的を説明してください（任意）",
+      "test": "現在のバリエーションでテスト",
+      "test-pass": "すべてのバリエーションがスキーマに一致しています。",
+      "test-fail": "{{count}}件のバリエーションがスキーマに一致していません。",
+      "test-valid": "有効",
+      "test-invalid": "無効"
+    },
     "clone-title": "フィーチャーフラグを複製",
     "clone-desc": "元のフラグのターゲティングルールをフラグがオフの状態で宛先環境の新しいフラグにコピーします。前提条件、フラグを条件としたルール、およびセグメントを条件としたルールはコピーされません。",
     "flag-id": "フラグID",

ui/dashboard/src/@locales/ja/message.json

@@ -3,6 +3,10 @@
   "validation": {
     "must-be-number": "数値を入力してください",
     "must-be-json": "JSONを入力してください",
+    "value-schema-violation": "この値はフラグの値スキーマに一致していません",
+    "value-schema-enum-not-number": "許可される値はすべて数値である必要があります",
+    "value-schema-invalid-regex": "有効なRE2正規表現ではありません",
+    "value-schema-invalid-json-schema": "有効なJSONスキーマではありません",
     "must-be-yaml": "YAMLを入力してください",
     "must-be-unique": "一意の値を入力してください",
     "max-length-number": "このフィールドの最大長は{{count}}桁です。",

ui/dashboard/src/pages/create-flag/form-schema.ts

@@ -9,10 +9,15 @@ import {
 import { FormSchemaProps } from 'hooks/use-form-schema';
 import * as yaml from 'js-yaml';
 import * as yup from 'yup';
-import { FeatureVariation, FeatureVariationType } from '@types';
+import {
+  FeatureVariation,
+  FeatureVariationType,
+  VariationValueSchema
+} from '@types';
 import { isNumber } from 'utils/chart';
 import { isJsonString } from 'utils/converts';
 import { isUniqueValue } from 'utils/function';
+import { createValueValidator } from 'utils/variation-value-schema';
 import { FlagSwitchVariationType } from './types';
 
 const nameSchema = ({ requiredMessage, translation }: FormSchemaProps) =>
@@ -129,6 +134,31 @@ export const createVariationsSchema = ({
               }
               return true;
             })
+            .test('matchesValueSchema', (value, context) => {
+              const root = context.from && context.from[1].value;
+              const valueSchema: VariationValueSchema | null | undefined =
+                root?.variationValueSchema;
+              if (!valueSchema || !value) return true;
+              const validator = createValueValidator(
+                valueSchema,
+                root.variationType
+              );
+              // Unable to validate client-side; the backend validates on save.
+              if (!validator) return true;
+              const result = validator(value);
+              if (result.valid) return true;
+              const message = translation(
+                'message:validation.value-schema-violation'
+              );
+              return context.createError({
+                // Append the failing JSON path/rule when the validator can
+                // identify it, so users know which field to fix.
+                message: result.detail
+                  ? `${message} (${result.detail})`
+                  : message,
+                path: context.path
+              });
+            })
             .test('isUnique', function (_, context) {
               const type = context.from && context.from[1].value.variationType;
               const variations: FeatureVariation[] =

ui/dashboard/src/pages/feature-flag-details/variation/form-schema.ts

@@ -1,6 +1,6 @@
 import { FormSchemaProps } from 'hooks/use-form-schema';
 import * as yup from 'yup';
-import { FeatureVariationType } from '@types';
+import { FeatureVariationType, VariationValueSchema } from '@types';
 import {
   createVariationsSchema,
   VariationSchema
@@ -14,11 +14,16 @@ export const variationsFormSchema = ({
     variationType: yup.mixed<FeatureVariationType>().required(requiredMessage),
     onVariation: yup.string(),
     offVariation: yup.string(),
+    variationValueSchema: yup
+      .mixed<VariationValueSchema>()
+      .nullable()
+      .default(null),
     variations: createVariationsSchema({ requiredMessage, translation })
   });
 export interface VariationForm {
   variationType: FeatureVariationType;
   onVariation: string;
   offVariation: string;
+  variationValueSchema?: VariationValueSchema | null;
   variations: VariationSchema[];
 }

ui/dashboard/src/pages/feature-flag-details/variation/index.tsx

@@ -36,6 +36,7 @@ import ConfirmationRequiredModal, {
 import { SCHEDULE_TYPE_SCHEDULE } from '../elements/confirm-required-modal/form-schema';
 import ScheduledChangesBanner from '../elements/scheduled-changes-banner';
 import { variationsFormSchema } from './form-schema';
+import SchemaSection from './schema-section';
 import SubmitBar from './submit-bar';
 import VariationsSection from './variations-section';
 
@@ -87,16 +88,23 @@ const Variation = ({ feature, editable }: VariationProps) => {
       variations: feature.variations,
       variationType: feature.variationType,
       offVariation: feature.offVariation,
-      onVariation: ''
+      onVariation: '',
+      variationValueSchema: feature.variationValueSchema ?? null
     },
     mode: 'onChange'
   });
 
   const {
     getValues,
+    watch,
     formState: { isDirty, isSubmitting }
   } = form;
 
+  const isSchemaChanged = !isEqual(
+    watch('variationValueSchema') ?? null,
+    feature.variationValueSchema ?? null
+  );
+
   const handleCheckVariations = useCallback(
     (variations: FeatureVariation[]) => {
       const { variations: featureVariations } = feature;
@@ -139,9 +147,14 @@ const Variation = ({ feature, editable }: VariationProps) => {
     async (additionalValues?: ConfirmRequiredValues) => {
       if (editable) {
         try {
-          const { variations, offVariation } = form.getValues();
+          const { variations, offVariation, variationValueSchema } =
+            form.getValues();
           const { comment, resetSampling, scheduleType, scheduleAt } =
             additionalValues || {};
+          const isSchemaUpdated = !isEqual(
+            variationValueSchema ?? null,
+            feature.variationValueSchema ?? null
+          );
 
           const isScheduleUpdate = scheduleType === SCHEDULE_TYPE_SCHEDULE;
 
@@ -179,6 +192,11 @@ const Variation = ({ feature, editable }: VariationProps) => {
               comment,
               resetSamplingSeed: resetSampling,
               offVariation,
+              ...(isSchemaUpdated
+                ? variationValueSchema
+                  ? { variationValueSchema }
+                  : { clearVariationValueSchema: true }
+                : {}),
               ...handleCheckVariations(variations)
             });
             if (resp) {
@@ -202,7 +220,8 @@ const Variation = ({ feature, editable }: VariationProps) => {
   useEffect(() => {
     form.reset({
       ...getValues(),
-      variations: feature.variations
+      variations: feature.variations,
+      variationValueSchema: feature.variationValueSchema ?? null
     });
   }, [feature]);
   useUnsavedLeavePage({ isShow: isDirty && !isSubmitting });
@@ -267,6 +286,7 @@ const Variation = ({ feature, editable }: VariationProps) => {
                 )}
               />
             )}
+            <SchemaSection feature={feature} editable={editable} />
             <VariationsSection
               editable={editable && !waitingRunningRollouts.length}
               feature={feature}
@@ -279,7 +299,11 @@ const Variation = ({ feature, editable }: VariationProps) => {
         <ConfirmationRequiredModal
           feature={feature}
           isOpen={openConfirmDialog}
-          isShowScheduleSelect={SCHEDULED_FLAG_CHANGES_ENABLED}
+          // Schema changes are not supported by scheduled flag changes,
+          // so only offer scheduling when the schema is unchanged.
+          isShowScheduleSelect={
+            SCHEDULED_FLAG_CHANGES_ENABLED && !isSchemaChanged
+          }
           onClose={onCloseConfirmDialog}
           onSubmit={additionalValues =>
             form.handleSubmit(() => onSubmit(additionalValues))()