AWS bedrock documentation change
Summary
Added 'Policy creation best practices' section with guidance on variable creation, validation rules, naming conventions, and logic structure for Automated Reasoning policies
Security assessment
The changes provide general policy design best practices focused on improving validation logic and reducing errors, but there's no explicit mention of security vulnerabilities, access controls, or security-specific features. The guidance aims to improve policy correctness rather than address security flaws.
Diff
diff --git a/bedrock/latest/userguide/create-automated-reasoning-policy.md b/bedrock/latest/userguide/create-automated-reasoning-policy.md index fe44b914b..db8966b36 100644 --- a//bedrock/latest/userguide/create-automated-reasoning-policy.md +++ b//bedrock/latest/userguide/create-automated-reasoning-policy.md @@ -5 +5 @@ -Create your Automated Reasoning policy in the consoleCreate your Automated Reasoning policy using the APIView Automated Reasoning policy details +Create your Automated Reasoning policy in the consoleCreate your Automated Reasoning policy using the APIView Automated Reasoning policy detailsPolicy creation best practices @@ -132,0 +133,106 @@ After you create your policy, you can view its the translated logic and variable +## Policy creation best practices + +Good Automated Reasoning policies capture all the information necessary to validate content from your application. At a high level, the policy should return a validation result of VALID when you deem you LLM's answer to be valid and complete. + +### Create variables that capture user intent and use implications (=>) to structure relationships + +Use boolean variables to capture the conclusion a user is driving towards, such as "can I submit this form," or "is this payment compliant," and then use the variables to create rules that follow an if/then "implicative form." You can use the content description field while creating a policy to give examples of the type of questions users will ask or give direct guidance on what these variables should be. + +**Example:** + + + ✓ Good: (=> isPaymentCompliant (<= paymentAmount 10000)) + + ✗ Poor: (<= paymentAmount 10000) + +### Use booleans instead of enums for non-exclusive states + +Represent characteristics that can co-exist as separate boolean variables rather than as mutually exclusive enum values. This prevents logical contradictions when multiple conditions can apply simultaneously. For example, a user can be both a veteran and a teacher. Two boolean variables allow both to be set true. Using enum values to set customerType to TEACHER and customerType to VETERAN causes a contradiction since a variable can only have a single value. + +**Example:** + + + ✓ Good: isTeacher, isVeteran + + ✗ Poor: customerType = {TEACHER, VETERAN, OTHER} + +### Specify units and formats explicitly in variable descriptions + +Clearly document the unit and format for all numerical values in their descriptions. This reduces variance when interpreting text with different formats and prevents unit conversion errors, leading to more predictable validation results. + +**Examples:** + + * "discountRate: Decimal representation of percentage (0.15 means 15%)" + + * "refundTimeframeInDays: Number of days allowed for refund requests" + + * "temperatureInCelsius: Integer value in degrees Celsius" + + + + +### Validate ranges for numerical values + +Use rules to validate variable values to ensure they are valid. Setting these constraints for numerical variables can guard against non-sensical inputs and highlight them as "impossible" when they occur. + +**Example:** + + + ✓ Good: (> patientAge 0) + + ✓ Good: (and (> creditScore 300) (< creditScore 1100)) + +### Use intermediate variables to model different levels and create abstractions + +Use meaningful intermediate variables to represent complex concepts and connect them explicitly to implementation details. Using conceptual variables instead of explicit expressions creates modularity and makes the logical flow from policy concepts to specific outcomes clear. This also allows validation on generic cases where the explicit inputs are not present, for example: "Do premium benefits include free upgrades?" + +**Example:** + + + (=> (or (> membershipDurationYears 10) + lifeTimeStatusGranted) + hasLifetimeStatus) + + (= qualifiesForPremiumBenefits + (or isPlatinumMember hasLifetimeStatus)) + + (=> qualifiesForPremiumBenefits freeUpgrade) + +### Use enums for categorization and subjective assessments + +Define enumerated types for categorizing issues or representing subjective judgments rather than using numerical scales. Discrete categories allow clear definitions to be assigned for each severity. Numerical scales do not provide a consistent means of categorization. If it's possible for a variable not to have a value from the enum, include an `OTHER` or `NONE` among the possible values. + +**Example:** + + + type "Severity" with values "CRITICAL", "MAJOR", "MINOR" + +### Logic must be declarative and not procedural + +Standard computer code executes in a given order but policies specify rules that do not execute in a given order. Design rules and variables to allow if/then/else logic within a single rule. This approach allows rules to remain decoupled and avoids rule conflicts while still clearly representing the logical structure of the policy. + +**Example:** + + + ✗ Poor: (=> conditionA (= outcome VALUE_1)) + ✗ Poor: (=> conditionB (= outcome VALUE_2)) + + ✓ Good: (=> (and conditionA conditionB) (= outcome VALUE_1)) // A takes precedence when both apply + ✓ Good: (=> (and (not conditionA) conditionB) (= outcome VALUE_2)) + ✓ Good: (=> (and (not conditionA) (not conditionB)) (= outcome DEFAULT_VALUE)) + +### Use clear and consistent naming conventions + +Apply predictable patterns in variable naming to enhance readability and consistent interpretation. + +**Examples:** + + * Boolean variables: use "is" or "has" prefix + + * Categorical variables: use substantive nouns + + * Numerical variables: include units when appropriate + + + +