Policy-definition advanced parameter annotation + static check + UI grouping

[Tharsanan1]

Policy-definition advanced parameter annotation + static check + UI grouping

Context

We discussed improving how policy parameters are shown in Basic Settings vs Advanced Settings, and adding static validation to prevent invalid advanced-required configurations.

Proposed annotations

At root property level under parameters.properties:

• x-wso2-policy-advanced-param: true|false
  • If missing, treat as false.

For config-linked defaults:

• Rename annotation key from wso2/defaultValue to x-wso2-policy-default-config.
• x-wso2-policy-default-config will be the standard key going forward.

Proposed behavior

1. Static check in PR validation

• If a root property under parameters.properties is marked x-wso2-policy-advanced-param: true and is required, it must have a JSON Schema default.
• If default is missing, static check fails.
• Requiredness detection should include:
  • direct required: [...]
  • conditional requiredness through anyOf / allOf / if-then.

2. UI grouping logic (Basic vs Advanced)

• Show in the policy landing view (not a new section) when:
  • x-wso2-policy-advanced-param is false, or
  • annotation is missing.
• Show in Advanced/Additional Settings when:
  • x-wso2-policy-advanced-param is true.
• For nested properties:
  • decision is based only on the root property annotation.
  • do not evaluate child-level advanced annotations.
  • if root is advanced, entire property block goes to Advanced.

Scope for this discussion

• annotation contract for advanced parameter grouping
• annotation rename contract: wso2/defaultValue -> x-wso2-policy-default-config
• PR static check rule for advanced+required+default
• UI rendering behavior based on root property annotation

Acceptance criteria

1. x-wso2-policy-advanced-param and x-wso2-policy-default-config are recognized by policy-definition validation/static-check logic.
2. x-wso2-policy-default-config is documented as the replacement for wso2/defaultValue.
3. PR checks fail when an advanced required root property in parameters has no JSON Schema default.
4. Requiredness evaluation includes direct and conditional requiredness.
5. UI shows Basic/Advanced sections using root-level advanced annotation, defaulting missing annotation to Basic.
6. Nested grouping is decided only at root property level.

Example

parameters:
  type: object
  required: [responseHeaders]
  properties:
    some-advance-prop:
      type: array
      x-wso2-policy-advanced-param: true
      default: []
      x-wso2-policy-default-config: "${config.policy_configurations.sample.response_headers}"
      items:
        type: object