0
# Validation Components
1

2
The validation components provide validators for AWS-specific endpoint rules, built-in parameters, and special case configurations. These validators ensure proper configuration and usage of AWS endpoint features in Smithy models.
3

4
## Capabilities
5

6
### AWS Built-in Validator
7

8
#### RuleSetAwsBuiltInValidator
9
```java { .api }
10
/**
11
 * Validator for AWS built-in parameters in rule sets.
12
 * Ensures proper usage of AWS-specific built-in parameters in endpoint rules.
13
 */
14
public final class RuleSetAwsBuiltInValidator implements Validator {
15
    /**
16
     * Validates AWS built-in parameter usage across the model
17
     * @param model Smithy model to validate
18
     * @return Stream of validation events
19
     */
20
    public Stream<ValidationEvent> validate(Model model);
21
    
22
    /**
23
     * Gets the validator name
24
     * @return Validator identifier
25
     */
26
    public String getName();
27
}
28
```
29

30
### Special Case Validator
31

32
#### AwsSpecialCaseEndpointValidator
33
```java { .api }
34
/**
35
 * Validator for AWS endpoint special case configurations.
36
 * Validates special case endpoint configurations for AWS services.
37
 */
38
public final class AwsSpecialCaseEndpointValidator implements Validator {
39
    /**
40
     * Validates AWS special case endpoint configurations
41
     * @param model Smithy model to validate
42
     * @return Stream of validation events
43
     */
44
    public Stream<ValidationEvent> validate(Model model);
45
    
46
    /**
47
     * Gets the validator name
48
     * @return Validator identifier
49
     */
50
    public String getName();
51
}
52
```
53

54
### Migration Utilities
55

56
#### EndpointSigV4Migration
57
```java { .api }
58
/**
59
 * Migration utility for SigV4 endpoint configurations.
60
 * Handles migration of endpoint authentication configurations.
61
 */
62
public final class EndpointSigV4Migration implements DiffEvaluator {
63
    /**
64
     * Evaluates differences in endpoint SigV4 configurations
65
     * @param context Diff evaluation context
66
     * @return List of differences found
67
     */
68
    public List<ValidationEvent> evaluate(DiffEvaluator.Context context);
69
    
70
    /**
71
     * Gets the evaluator name
72
     * @return Evaluator identifier
73
     */
74
    public String getName();
75
}
76
```
77

78
**Usage Examples:**
79

80
```java
81
import software.amazon.smithy.rulesengine.aws.validators.*;
82
import software.amazon.smithy.model.validation.ValidatedResult;
83
import software.amazon.smithy.model.Model;
84

85
// Validate a model with AWS validators
86
Model model = // ... load your model
87
ValidatedResult<Model> result = Model.assembler()
88
    .addValidator(new RuleSetAwsBuiltInValidator())
89
    .addValidator(new AwsSpecialCaseEndpointValidator())
90
    .assemble();
91

92
// Check for validation errors
93
if (result.isBroken()) {
94
    result.getValidationEvents().forEach(event -> {
95
        System.err.println(event.getSeverity() + ": " + event.getMessage());
96
    });
97
}
98

99
// Use in diff evaluation for migrations
100
EndpointSigV4Migration migration = new EndpointSigV4Migration();
101
// Applied automatically during model diffing
102
```
103

104
## Validation Rules
105

106
### AWS Built-in Parameter Validation
107

108
The `RuleSetAwsBuiltInValidator` enforces these rules:
109

110
#### Required Parameter Validation
111
- Validates that required AWS built-ins are properly configured
112
- Ensures built-in parameters have correct types and default values
113
- Checks that built-in references match available parameters
114

115
#### Parameter Usage Validation
116
- Validates that service-specific built-ins are only used by appropriate services
117
- Ensures S3 built-ins (`S3_*`) are only used in S3 endpoint rules
118
- Validates STS built-ins (`STS_*`) are only used in STS endpoint rules
119
- Checks S3Control built-ins (`S3_CONTROL_*`) usage
120

121
#### Type Consistency
122
- Ensures boolean built-ins are used as booleans
123
- Validates string built-ins are used as strings
124
- Checks parameter references match declared types
125

126
### Common Validation Errors
127

128
```java
129
// Example validation events that might be generated:
130

131
// Invalid built-in usage
132
ValidationEvent error1 = ValidationEvent.builder()
133
    .severity(Severity.ERROR)
134
    .message("S3-specific built-in 'AWS::S3::Accelerate' cannot be used in non-S3 service")
135
    .sourceLocation(SourceLocation.none())
136
    .build();
137

138
// Missing required parameter
139
ValidationEvent error2 = ValidationEvent.builder()
140
    .severity(Severity.ERROR) 
141
    .message("Required built-in parameter 'AWS::Region' is not defined")
142
    .sourceLocation(SourceLocation.none())
143
    .build();
144

145
// Type mismatch
146
ValidationEvent error3 = ValidationEvent.builder()
147
    .severity(Severity.ERROR)
148
    .message("Built-in 'AWS::UseDualStack' expects boolean value, got string")
149
    .sourceLocation(SourceLocation.none())
150
    .build();
151
```
152

153
### Special Case Endpoint Validation
154

155
The `AwsSpecialCaseEndpointValidator` enforces these rules:
156

157
#### Partition Validation
158
- Validates that partition names in special cases are valid AWS partitions
159
- Ensures partition-specific configurations are appropriate
160
- Checks partition compatibility with endpoint patterns
161

162
#### Endpoint Template Validation
163
- Validates endpoint template syntax and placeholders
164
- Ensures required template variables are available
165
- Checks endpoint template compatibility with service patterns
166

167
#### Capability Validation
168
- Validates FIPS and dual-stack capability declarations
169
- Ensures capability combinations are supported
170
- Checks capability consistency across partitions
171

172
### Common Special Case Validation Errors
173

174
```java
175
// Example special case validation events:
176

177
// Invalid partition
178
ValidationEvent error1 = ValidationEvent.builder()  
179
    .severity(Severity.ERROR)
180
    .message("Unknown AWS partition 'aws-invalid' in special case configuration")
181
    .sourceLocation(SourceLocation.none())
182
    .build();
183

184
// Invalid endpoint template
185
ValidationEvent error2 = ValidationEvent.builder()
186
    .severity(Severity.ERROR)
187
    .message("Endpoint template contains undefined variable: {invalid}")
188
    .sourceLocation(SourceLocation.none())
189
    .build();
190

191
// Inconsistent capabilities
192
ValidationEvent error3 = ValidationEvent.builder()
193
    .severity(Severity.WARNING)
194
    .message("FIPS capability declared but not supported in partition 'aws-cn'")
195
    .sourceLocation(SourceLocation.none())
196
    .build();
197
```
198

199
## Service Registration
200

201
The validators are automatically registered through the Java Service Provider Interface:
202

203
```
204
META-INF/services/software.amazon.smithy.model.validation.Validator
205
```
206

207
Registration includes:
208
- `RuleSetAwsBuiltInValidator`
209
- `AwsSpecialCaseEndpointValidator`
210

211
The migration utility is registered through:
212

213
```
214
META-INF/services/software.amazon.smithy.diff.DiffEvaluator
215
```
216

217
Registration includes:
218
- `EndpointSigV4Migration`
219

220
## Integration with Model Assembly
221

222
### Automatic Validation
223

224
```java
225
// Validators are automatically applied during model assembly
226
Model model = Model.assembler()
227
    .discoverModels(getClass().getClassLoader())
228
    .assemble()
229
    .unwrap(); // Validators run automatically
230

231
// Manual validator application
232
ValidatedResult<Model> result = Model.assembler()
233
    .addValidator(new RuleSetAwsBuiltInValidator())
234
    .addValidator(new AwsSpecialCaseEndpointValidator())
235
    .discoverModels()
236
    .assemble();
237
```
238

239
### Custom Validation Context
240

241
```java
242
// Create custom validation context for specific scenarios
243
ValidationEvent.Builder eventBuilder = ValidationEvent.builder()
244
    .severity(Severity.ERROR)
245
    .sourceLocation(shape.getSourceLocation())
246
    .shapeId(shape.getId());
247

248
// Apply context-specific validation rules
249
if (isAwsService(shape)) {
250
    // Apply AWS-specific validation
251
    validator.validateAwsService(shape, eventBuilder);
252
}
253
```
254

255
### Migration Evaluation
256

257
```java
258
// Evaluate model differences for migrations
259
ModelDiff diff = ModelDiff.builder()
260
    .oldModel(oldModel)
261
    .newModel(newModel)
262
    .build();
263

264
DiffEvaluator.Context context = DiffEvaluator.Context.builder()
265
    .diff(diff)
266
    .oldModel(oldModel)
267
    .newModel(newModel)
268
    .build();
269

270
EndpointSigV4Migration migration = new EndpointSigV4Migration();
271
List<ValidationEvent> migrationEvents = migration.evaluate(context);
272
```
273

274
## Best Practices
275

276
### Model Validation Workflow
277

278
1. **Early Validation**: Run validators during development
279
2. **Comprehensive Testing**: Include validation in CI/CD pipelines  
280
3. **Error Handling**: Properly handle and report validation events
281
4. **Incremental Validation**: Validate changes during model evolution
282

283
### Custom Validator Integration
284

285
```java
286
// Extend validation for custom requirements
287
public class CustomAwsValidator implements Validator {
288
    @Override
289
    public Stream<ValidationEvent> validate(Model model) {
290
        return model.shapes()
291
            .filter(this::hasAwsTraits)
292
            .flatMap(this::validateAwsConfiguration);
293
    }
294
    
295
    private boolean hasAwsTraits(Shape shape) {
296
        return shape.hasTrait(RuleBasedEndpointsTrait.class) ||
297
               shape.hasTrait(EndpointModifierTrait.class);
298
    }
299
}
300
```
301

302
### Migration Best Practices
303

304
```java
305
// Safe migration patterns
306
public void performMigration(Model oldModel, Model newModel) {
307
    // 1. Validate both models
308
    validateModel(oldModel);
309
    validateModel(newModel);
310
    
311
    // 2. Evaluate migration
312
    List<ValidationEvent> migrationIssues = evaluateMigration(oldModel, newModel);
313
    
314
    // 3. Handle breaking changes
315
    migrationIssues.stream()
316
        .filter(event -> event.getSeverity() == Severity.ERROR)
317
        .forEach(this::handleBreakingChange);
318
}
319
```