feat: add EL resolution for dynamic subscription form options - domain layer

Introduces SubscriptionFormElResolverDomainService with EL-based resolution of dynamic schema options and constraints, backed by API/environment metadata. Extends Constraint and SubscriptionFormSchema models with dynamic variants. Adds ApiMetadataQueryService#findApiMetadata and introduces no-context overloads that return fallbacks directly when no API context is available.

Author: JedrzejJanasiak

gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/api/query_service/ApiMetadataQueryService.java

@@ -16,15 +16,14 @@
 package io.gravitee.apim.core.api.query_service;
 
 import io.gravitee.apim.core.api.model.ApiMetadata;
-import io.gravitee.rest.api.service.common.ExecutionContext;
 import java.util.Map;
 
 public interface ApiMetadataQueryService {
     /**
-     * Find all metadata with their default value for an API.
+     * Find all metadata for an API, merging environment-level defaults with API-level overrides.
      * @param environmentId The environment id.
      * @param apiId The API id.
-     * @return A map of metadata key and metadata.
+     * @return A map of metadata key to metadata (API value takes precedence over env default).
      */
     Map<String, ApiMetadata> findApiMetadata(String environmentId, String apiId);
 }

gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/subscription_form/domain_service/SubscriptionFormConstraintsFactory.java

@@ -20,6 +20,7 @@
 import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema;
 import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema.CheckboxField;
 import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema.CheckboxGroupField;
+import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema.DynamicOptionsAttribute;
 import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema.Field;
 import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema.InputField;
 import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema.MinLengthAttribute;
@@ -61,17 +62,27 @@ private static List<Constraint> constraintsFor(Field field) {
         }
 
         var out = new ArrayList<Constraint>();
+        addRequiredConstraint(field, out);
+        addLengthConstraints(field, out);
+        addPatternConstraint(field, out);
+        addOptionsConstraint(field, out);
+        return out;
+    }
 
-        if (field.required()) {
-            if (field instanceof CheckboxField) {
-                out.add(new Constraint.MustBeTrue());
-            } else if (field instanceof CheckboxGroupField) {
-                out.add(new Constraint.NonEmptySelection());
-            } else {
-                out.add(new Constraint.Required());
-            }
+    private static void addRequiredConstraint(Field field, List<Constraint> out) {
+        if (!field.required()) {
+            return;
         }
+        if (field instanceof CheckboxField) {
+            out.add(new Constraint.MustBeTrue());
+        } else if (field instanceof CheckboxGroupField) {
+            out.add(new Constraint.NonEmptySelection());
+        } else {
+            out.add(new Constraint.Required());
+        }
+    }
 
+    private static void addLengthConstraints(Field field, List<Constraint> out) {
         if (field instanceof MinLengthAttribute min && min.minLength() != null) {
             out.add(new Constraint.MinLength(min.minLength()));
         }
@@ -82,19 +93,28 @@ private static List<Constraint> constraintsFor(Field field) {
                 textarea.maxLength() != null ? Constraint.MaxLength.forTextarea(textarea.maxLength()) : Constraint.MaxLength.forTextarea()
             );
         }
+    }
+
+    private static void addPatternConstraint(Field field, List<Constraint> out) {
         if (field instanceof PatternAttribute pat && pat.pattern() != null) {
             out.add(new Constraint.MatchesPattern(pat.pattern()));
         }
+    }
 
-        if (field instanceof OptionsAttribute opt && hasOptions(opt.options())) {
+    private static void addOptionsConstraint(Field field, List<Constraint> out) {
+        if (field instanceof DynamicOptionsAttribute dyn && dyn.dynamicOptions() != null) {
+            if (field instanceof CheckboxGroupField) {
+                out.add(new Constraint.DynamicEachOf(dyn.dynamicOptions().expression(), dyn.dynamicOptions().fallback()));
+            } else {
+                out.add(new Constraint.DynamicOneOf(dyn.dynamicOptions().expression(), dyn.dynamicOptions().fallback()));
+            }
+        } else if (field instanceof OptionsAttribute opt && hasOptions(opt.options())) {
             if (field instanceof CheckboxGroupField) {
                 out.add(new Constraint.EachOf(opt.options()));
             } else {
                 out.add(new Constraint.OneOf(opt.options()));
             }
         }
-
-        return out;
     }
 
     private static boolean hasOptions(List<String> options) {

gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/subscription_form/domain_service/SubscriptionFormElResolverDomainService.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright © 2015 The Gravitee team (http://gravitee.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.gravitee.apim.core.subscription_form.domain_service;
+
+import io.gravitee.apim.core.subscription_form.model.SubscriptionFormFieldConstraints;
+import io.gravitee.apim.core.subscription_form.model.SubscriptionFormSchema;
+import jakarta.annotation.Nonnull;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Resolves EL expressions embedded in subscription form option fields.
+ *
+ * <p>Used in two contexts:</p>
+ * <ul>
+ *   <li><b>Form retrieval</b> — resolves {@link SubscriptionFormSchema.DynamicOptions} expressions for
+ *       option-bearing fields and returns a {@code fieldKey → resolved options} map to the frontend.</li>
+ *   <li><b>Subscription validation</b> — replaces {@link io.gravitee.apim.core.subscription_form.model.Constraint.DynamicOneOf}
+ *       and {@link io.gravitee.apim.core.subscription_form.model.Constraint.DynamicEachOf} constraints with
+ *       their resolved static equivalents before the validator runs.</li>
+ * </ul>
+ *
+ * <p>Each method has two variants: one that accepts an API context (environment + API id) for full metadata
+ * resolution, and one without — for situations where no API context is available (e.g. Console Form Builder).
+ * The no-context variants use the configured fallback values directly.</p>
+ *
+ * @author Gravitee.io Team
+ */
+public interface SubscriptionFormElResolverDomainService {
+    /**
+     * Resolves EL expressions for all dynamic-option fields in the schema against API + environment metadata.
+     *
+     * @param schema        the subscription form schema
+     * @param environmentId the environment identifier
+     * @param apiId         the API identifier
+     * @return a map of {@code fieldKey → effective option list} for every field that has dynamic options
+     */
+    Map<String, List<String>> resolveSchemaOptions(SubscriptionFormSchema schema, String environmentId, String apiId);
+
+    /**
+     * No-context variant — returns an empty map; callers should display the fallback values from the schema.
+     */
+    Map<String, List<String>> resolveSchemaOptions(SubscriptionFormSchema schema);
+
+    /**
+     * Pre-resolves {@link io.gravitee.apim.core.subscription_form.model.Constraint.DynamicOneOf} and
+     * {@link io.gravitee.apim.core.subscription_form.model.Constraint.DynamicEachOf} constraints to their
+     * static equivalents using API + environment metadata.
+     *
+     * @param constraints   the stored constraints (may contain dynamic variants)
+     * @param environmentId the environment identifier
+     * @param apiId         the API identifier
+     * @return a new {@link SubscriptionFormFieldConstraints} with all dynamic constraints resolved
+     */
+    SubscriptionFormFieldConstraints resolveConstraints(
+        @Nonnull SubscriptionFormFieldConstraints constraints,
+        String environmentId,
+        String apiId
+    );
+
+    /**
+     * No-context variant — resolves dynamic constraints to their static equivalents using configured fallback values.
+     */
+    SubscriptionFormFieldConstraints resolveConstraints(@Nonnull SubscriptionFormFieldConstraints constraints);
+}

gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/subscription_form/model/Constraint.java

@@ -50,6 +50,8 @@
         @JsonSubTypes.Type(value = Constraint.MatchesPattern.class, name = "matchesPattern"),
         @JsonSubTypes.Type(value = Constraint.OneOf.class, name = "oneOf"),
         @JsonSubTypes.Type(value = Constraint.EachOf.class, name = "eachOf"),
+        @JsonSubTypes.Type(value = Constraint.DynamicOneOf.class, name = "dynamicOneOf"),
+        @JsonSubTypes.Type(value = Constraint.DynamicEachOf.class, name = "dynamicEachOf"),
     }
 )
 public sealed interface Constraint
@@ -62,7 +64,9 @@ public sealed interface Constraint
         Constraint.MaxLength,
         Constraint.MatchesPattern,
         Constraint.OneOf,
-        Constraint.EachOf {
+        Constraint.EachOf,
+        Constraint.DynamicOneOf,
+        Constraint.DynamicEachOf {
     /**
      * Whether the submitted value satisfies this constraint. The value is already trimmed; an empty string means absent.
      */
@@ -248,6 +252,42 @@ public String formatErrorMessage(String fieldKey, String value) {
         }
     }
 
+    /**
+     * Placeholder for a single-value option constraint whose allowed set is resolved at runtime from an EL expression.
+     *
+     * <p>This constraint is stored in the database and must be pre-resolved to a {@link OneOf} constraint
+     * (using the expression against the target API's metadata) before being passed to the validator.
+     * Its {@link #check(String)} throws {@link IllegalStateException} — it must never be evaluated directly.</p>
+     */
+    record DynamicOneOf(String expression, List<String> fallback) implements Constraint {
+        @Override
+        public boolean check(String value) {
+            throw new IllegalStateException("DynamicOneOf must be resolved before validation — call resolveConstraints() first");
+        }
+
+        @Override
+        public String formatErrorMessage(String fieldKey, String value) {
+            throw new IllegalStateException("DynamicOneOf must be resolved before validation — call resolveConstraints() first");
+        }
+    }
+
+    /**
+     * Placeholder for a multi-value option constraint whose allowed set is resolved at runtime from an EL expression.
+     *
+     * <p>Same pre-resolution semantics as {@link DynamicOneOf}, but resolves to an {@link EachOf} constraint.</p>
+     */
+    record DynamicEachOf(String expression, List<String> fallback) implements Constraint {
+        @Override
+        public boolean check(String value) {
+            throw new IllegalStateException("DynamicEachOf must be resolved before validation — call resolveConstraints() first");
+        }
+
+        @Override
+        public String formatErrorMessage(String fieldKey, String value) {
+            throw new IllegalStateException("DynamicEachOf must be resolved before validation — call resolveConstraints() first");
+        }
+    }
+
     private static Stream<String> splitCsv(String value) {
         return Arrays.stream(value.split(","))
             .map(String::trim)

gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/subscription_form/model/SubscriptionFormSchema.java

@@ -58,6 +58,19 @@ public interface OptionsAttribute {
         List<String> options();
     }
 
+    public interface DynamicOptionsAttribute {
+        DynamicOptions dynamicOptions();
+    }
+
+    /**
+     * Holds an EL expression and its fallback option list for option-bearing fields.
+     *
+     * <p>GMD syntax: {@code options="${expression}:fallback1,fallback2"}</p>
+     * <p>When present on a field, the expression is resolved at retrieval time against the
+     * target API's metadata. If resolution fails, {@code fallback} is used instead.</p>
+     */
+    public record DynamicOptions(String expression, List<String> fallback) {}
+
     /**
      * Marker interface for all field types in a subscription form schema.
      * Each implementation captures only the validation attributes relevant to its component type.
@@ -82,16 +95,23 @@ public record InputField(
     public record TextareaField(String fieldKey, boolean required, String readonlyValue, Integer minLength, Integer maxLength) implements
         Field, ReadOnlyValueAttribute, MinLengthAttribute, MaxLengthAttribute {}
 
-    /** Single-value dropdown — supports required, options. No readonly (not supported by the GMD component). */
-    public record SelectField(String fieldKey, boolean required, List<String> options) implements Field, OptionsAttribute {}
+    /** Single-value dropdown — supports required, static options, or dynamic EL options. No readonly (not supported by the GMD component). */
+    public record SelectField(String fieldKey, boolean required, List<String> options, DynamicOptions dynamicOptions) implements
+        Field, OptionsAttribute, DynamicOptionsAttribute {}
 
-    /** Single-value radio group — supports required, readonly, options. */
-    public record RadioField(String fieldKey, boolean required, String readonlyValue, List<String> options) implements
-        Field, ReadOnlyValueAttribute, OptionsAttribute {}
+    /** Single-value radio group — supports required, readonly, static options, or dynamic EL options. */
+    public record RadioField(
+        String fieldKey,
+        boolean required,
+        String readonlyValue,
+        List<String> options,
+        DynamicOptions dynamicOptions
+    ) implements Field, ReadOnlyValueAttribute, OptionsAttribute, DynamicOptionsAttribute {}
 
     /** Boolean checkbox — supports required, readonly. Value is "true"/"false". */
     public record CheckboxField(String fieldKey, boolean required, String readonlyValue) implements Field, ReadOnlyValueAttribute {}
 
-    /** Multi-value checkbox group — supports required, options. No readonly (not supported by the GMD component). */
-    public record CheckboxGroupField(String fieldKey, boolean required, List<String> options) implements Field, OptionsAttribute {}
+    /** Multi-value checkbox group — supports required, static options, or dynamic EL options. No readonly (not supported by the GMD component). */
+    public record CheckboxGroupField(String fieldKey, boolean required, List<String> options, DynamicOptions dynamicOptions) implements
+        Field, OptionsAttribute, DynamicOptionsAttribute {}
 }

gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/subscription_form/use_case/GetSubscriptionFormForEnvironmentUseCase.java

@@ -16,13 +16,22 @@
 package io.gravitee.apim.core.subscription_form.use_case;
 
 import io.gravitee.apim.core.UseCase;
+import io.gravitee.apim.core.subscription_form.domain_service.SubscriptionFormElResolverDomainService;
+import io.gravitee.apim.core.subscription_form.domain_service.SubscriptionFormSchemaGenerator;
 import io.gravitee.apim.core.subscription_form.exception.SubscriptionFormNotFoundException;
 import io.gravitee.apim.core.subscription_form.model.SubscriptionForm;
 import io.gravitee.apim.core.subscription_form.query_service.SubscriptionFormQueryService;
+import java.util.List;
+import java.util.Map;
+import lombok.Builder;
 import lombok.RequiredArgsConstructor;
 
 /**
- * Use case for getting the subscription form for an environment (the default form for that environment).
+ * Use case for getting the subscription form for an environment.
+ *
+ * <p>When {@link Input#apiId()} is non-null, EL expressions in option-bearing fields are resolved
+ * against the target API's metadata and returned in {@link Output#resolvedOptions()}.
+ * When null (e.g. Console Form Builder), only environment-level metadata is used for resolution.</p>
  *
  * @author Gravitee.io Team
  */
@@ -31,6 +40,8 @@
 public class GetSubscriptionFormForEnvironmentUseCase {
 
     private final SubscriptionFormQueryService subscriptionFormQueryService;
+    private final SubscriptionFormSchemaGenerator schemaGenerator;
+    private final SubscriptionFormElResolverDomainService elResolver;
 
     public Output execute(Input input) {
         var subscriptionForm = subscriptionFormQueryService
@@ -41,10 +52,25 @@ public Output execute(Input input) {
             throw new SubscriptionFormNotFoundException(input.environmentId());
         }
 
-        return new Output(subscriptionForm);
+        var schema = schemaGenerator.generate(subscriptionForm.getGmdContent());
+        var resolvedOptions = input.apiId() != null
+            ? elResolver.resolveSchemaOptions(schema, input.environmentId(), input.apiId())
+            : elResolver.resolveSchemaOptions(schema);
+
+        return new Output(subscriptionForm, resolvedOptions);
     }
 
-    public record Input(String environmentId, boolean onlyEnabled) {}
+    @Builder
+    public record Input(String environmentId, boolean onlyEnabled, String apiId) {
+        /**
+         * Backward-compatible constructor for callers that don't provide an API context.
+         * TODO: remove once the resource layer is wired (APIM-12990 resource PR).
+         */
+        @Deprecated
+        public Input(String environmentId, boolean onlyEnabled) {
+            this(environmentId, onlyEnabled, null);
+        }
+    }
 
-    public record Output(SubscriptionForm subscriptionForm) {}
+    public record Output(SubscriptionForm subscriptionForm, Map<String, List<String>> resolvedOptions) {}
 }

gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/subscription_form/use_case/UpdateSubscriptionFormUseCase.java

@@ -62,7 +62,12 @@ public Output execute(Input input) {
             );
 
         var gmd = GraviteeMarkdown.of(input.gmdContent());
-        var schema = schemaGenerator.generate(gmd);
+        SubscriptionFormSchema schema;
+        try {
+            schema = schemaGenerator.generate(gmd);
+        } catch (IllegalArgumentException e) {
+            throw new SubscriptionFormValidationException(List.of(e.getMessage()));
+        }
         validateFieldCount(schema);
         var constraints = SubscriptionFormConstraintsFactory.fromSchema(schema);
         existingForm.update(gmd, constraints);