Policy Parameters Rename Proposal

[Tharsanan1]

Policy Parameters Rename Proposal

Starting this thread to review proposed policy parameter renames across gateway policies.

Goals:

• improve clarity and consistency
• reduce ambiguous names
• make units and intent explicit where relevant

These are proposed changes, not final decisions.
Please review with focus on runtime behavior, schema compatibility, migration impact, and backward-compat strategy.

Policy Name	Current Name	Suggested Name	Reason for Suggestion
add-headers / modify-headers / remove-headers / set-headers	requestHeaders	request.headers	Groups header parameters into a structured object for consistency across all policies.
	responseHeaders	response.headers	Symmetry with the request configuration.
advanced-ratelimit	keyExtraction[].key	sourceKeyOrValue	Covers both semantics: source field name for header/metadata types and literal value for constant type.
	costExtraction.sources[].key	keyName	Consistency with key extraction naming.
analytics-header-filter	requestHeadersToFilter	request	Groups header filtering parameters into a structured object for consistency.
	requestHeadersToFilter.operation	request.mode	Renames "operation" to "mode" to match other ACL-like policies (allow/deny).
	requestHeadersToFilter.headers	request.headers	Nested under the new request object.
	responseHeadersToFilter	response	Symmetry with the request configuration.
	responseHeadersToFilter.operation	response.mode	Symmetry with the request configuration.
	responseHeadersToFilter.headers	response.headers	Symmetry with the request configuration.
api-key-auth	in	keyLocation	in is too terse; keyLocation clearly describes where the API key is expected.
	key	keyName	keyName more clearly describes that this is the identifier (header/query param name) for the API key.
	value-prefix	valuePrefix	Follows camelCase convention used throughout the project.
aws-bedrock-guardrail	request.redactPII	request.piiRedaction	Noun-based naming is more consistent for configuration properties.
azure-content-safety-content-moderation	hateCategory	hateSeverityThreshold	Clarifies that the integer value (0-7) represents a severity threshold, not a category toggle.
	sexualCategory	sexualSeverityThreshold	Same as above.
	selfHarmCategory	selfHarmSeverityThreshold	Same as above.
	violenceCategory	violenceSeverityThreshold	Same as above.
content-length-guardrail	request.min / max	request.minBytes / maxBytes	Explicitly states the unit of measurement (bytes).
	response.min / max	response.minBytes / maxBytes	Same as above.
cors	maxAge	maxAgeSeconds	Explicitly states the unit of measurement (seconds).
json-to-xml / xml-to-json	onRequestFlow	request.enabled	Groups flow control into request/response objects for better structure and consistency.
	onResponseFlow	response.enabled	Same as above.
jwt-auth	issuers	issuerOrKeyManagerNames	Runtime accepts both issuer values and key manager names; rename should preserve both semantics.
mcp-auth	issuers	keyManagerNames	Clarifies that this list maps to key manager names when deriving MCP protected-resource metadata issuers.
mcp-authz	rules[].attribute.name	rules[].attribute.identifier	Avoids ambiguity: tools/prompts match by name while resources match by URI.
mcp-rewrite	resources[].name	resources[].displayName	Clarifies that resource identity is driven by uri and this field is presentation-oriented.
	tools[].target / prompts[].target / resources[].target	tools[].targetName / prompts[].targetName / resources[].targetUri	Makes target semantics explicit per capability type instead of using one generic key.
jwt-auth	authHeaderPrefix	authScheme	Standardizes terminology to match RFC 7235 and existing system parameters.
	userIdClaim	userIdClaimName	Clarifies that this is the name of the claim to extract the ID from.
log-message	logRequestPayload	request.logPayload	Groups request-related logging parameters into a structured object.
	logRequestHeaders	request.logHeaders	Same as above.
	excludedRequestHeaders	request.excludedHeaders	Renames and converts from a comma-separated string to a proper array of strings.
	logResponsePayload	response.logPayload	Groups response-related logging parameters into a structured object.
	logResponseHeaders	response.logHeaders	Same as above.
	excludedResponseHeaders	response.excludedHeaders	Renames and converts from a comma-separated string to a proper array of strings.
model-round-robin / model-weighted-round-robin	suspendDuration	suspendDurationSeconds	Explicitly states the unit of measurement (seconds).
	requestModel.identifier	requestModel.keyNameOrPath	Clarifies that this can be a header name, query/path key, or JSONPath depending on location. Note: requestModel is currently runtime-required but not declared in policy schema.
pii-masking-regex	piiEntities	request.entities / response.entities	Groups parameters into request/response and removes redundant "pii" prefix.
	piiEntity	type	More standard naming for the PII category (e.g., EMAIL, PHONE).
	piiRegex	regex	Standardizes naming for regular expression patterns.
prompt-decorator	promptDecoratorConfig	decoration	Flattens the redundant structure to a single decoration object.
prompt-template	promptTemplateConfig	templates	Reflects collection semantics. Keep compatibility by accepting both JSON string and array/object forms during migration, normalize internally, then deprecate string later.
semantic-cache	ttl	ttlSeconds	Explicitly states the unit of measurement (seconds) for this system parameter.
semantic-prompt-guard	jsonPath / allowedPhrases ...	request.jsonPath / request.allowedPhrases ...	Groups all prompt guard parameters into a request object for consistency with other guardrail policies.
sentence-count-guardrail	request.min / max	request.minSentences / maxSentences	Explicitly states the unit of measurement (sentences).
	response.min / max	response.minSentences / maxSentences	Same as above.
token-based-ratelimit	count	limit	Standardizes terminology to match the advanced-ratelimit policy.
url-guardrail	request.timeout	request.timeoutMillis	Explicitly states the unit of measurement (milliseconds).
	response.timeout	response.timeoutMillis	Same as above.
	request.onlyDNS	request.useDnsOnly	More idiomatic boolean naming.
word-count-guardrail	request.min / max	request.minWords / maxWords	Explicitly states the unit of measurement (words).
	response.min / max	response.minWords / maxWords	Same as above.

[Tharsanan1]

I recommend using a similar skill and integrate Copilot reviews on PR checks

---
name: apiplatform-policy-review
description: Perform end-to-end API Platform gateway policy reviews by validating policy-definition.yaml against runtime behavior, parameter naming quality, required/optional/default correctness, schema-runtime drift, and test impact. Use when auditing a policy, reviewing rename proposals, checking integration-test failures caused by validation changes, or preparing action-oriented policy review notes.
---

API Platform Policy Review

Overview

Review a policy as a contract: schema, runtime parsing/validation, and observed behavior must align. Produce concrete, action-oriented findings with precise parameter paths and code references.

Review Scope

Cover these areas unless the user narrows scope:

• Parameter naming quality
• Schema/runtime type and shape alignment
• Required/optional/default correctness
• Request vs response phase semantics
• Validation strictness and integration-test impact
• Migration and compatibility risk for proposed changes

Workflow

1. Read contract first.

• Read policies/<policy>/policy-definition.yaml.
• Identify user parameters vs system parameters.
• Capture required fields, defaults, conditionals (anyOf/allOf/if-then), and additionalProperties behavior.

2. Read runtime behavior.

• Read policy implementation (*.go) focusing on GetPolicy, parsing helpers, and OnRequest/OnResponse.
• Record exact keys runtime reads and how it handles missing/invalid values.
• Verify whether policy is request-only, response-only, or dual-flow.

3. Compare schema vs runtime.

• Flag mismatches in accepted types, requiredness, defaults, and conditional behavior.
• Flag cases where schema allows config that runtime rejects (or vice versa).
• Flag cases where docs/comments imply behavior not implemented.

4. Assess naming quality.

• Prefer explicit names over overloaded/generic keys.
• Ensure numeric params carry unit semantics when needed.
• Ensure booleans read as toggles (useX, enableX, allowX).
• Ensure identity vs display fields are clearly separated.

5. Evaluate change impact.

• Determine if proposed rename/refactor is breaking.
• Recommend alias/transitional handling only when needed.
• Note integration-test updates required by stricter validation.

6. Produce review output.

• Findings first, most severe first.
• Include exact file path + parameter path + runtime evidence.
• Keep recommendations actionable and minimal.

Naming Rules

• Use names that reflect actual runtime semantics, not aspirational schema wording.
• Include units where values are unit-bound (*Seconds, *Millis, *Bytes, *Words, *Sentences).
• Avoid ambiguous keys (name, key, target) when meaning varies by capability/type.
• Use capability-specific names when one field currently carries multiple semantics.
• Use request.* / response.* structure only when phase intent is real in behavior.

Schema Best Practices

• Keep schema and runtime accepted shapes aligned.
• Do not rely on schema defaults that runtime ignores.
• Requiredness must match runtime assumptions.
• Conditional rules must be scoped correctly (for example, avoid if conditions that match when a field is absent).
• Keep rejection behavior predictable across validation layers.

Output Formats

When producing rename sheets (CSV/Markdown):

• Every row must be standalone.
• Avoid "Same as above".
• Reason should state:
  • what is ambiguous today
  • what the new name makes explicit

When producing findings:

• Include severity, parameter path, evidence, and action.
• Prefer short, direct findings over long narrative.

Final Checks

Before finishing:

• Verify every recommendation is backed by code behavior.
• Verify parameter paths exist in current schema.
• Verify proposed text does not imply unsupported runtime behavior.
• If both CSV and Markdown summaries are updated, ensure wording is aligned.