0
# Smithy Traits
1

2
The Smithy traits provide annotation capabilities for describing AWS endpoint behavior and configuration in Smithy models. These traits enable declarative specification of endpoint patterns, special cases, and AWS-specific endpoint requirements.
3

4
## Capabilities
5

6
### Endpoint Behavior Traits
7

8
#### RuleBasedEndpointsTrait
9
```java { .api }
10
/**
11
 * A trait that indicates that a service has handwritten endpoint rules.
12
 * Services marked with this trait have handwritten endpoint rules that extend or replace 
13
 * their standard generated endpoint rules through an external mechanism.
14
 */
15
public final class RuleBasedEndpointsTrait extends AnnotationTrait {
16
    /** Trait shape ID */
17
    public static final ShapeId ID = ShapeId.from("aws.endpoints#rulesBasedEndpoints");
18
    
19
    /**
20
     * Creates a new RuleBasedEndpointsTrait with empty configuration
21
     */
22
    public RuleBasedEndpointsTrait();
23
    
24
    /**
25
     * Creates a new RuleBasedEndpointsTrait from object node
26
     * @param node Configuration object node
27
     */
28
    public RuleBasedEndpointsTrait(ObjectNode node);
29
    
30
    /**
31
     * Trait provider for service registration
32
     */
33
    public static final class Provider extends AnnotationTrait.Provider<RuleBasedEndpointsTrait> {
34
        public Provider();
35
    }
36
}
37
```
38

39
#### StandardRegionalEndpointsTrait
40
```java { .api }
41
/**
42
 * A trait that indicates a service uses standard regional endpoint patterns.
43
 */
44
public final class StandardRegionalEndpointsTrait extends AnnotationTrait {
45
    /** Trait shape ID */
46
    public static final ShapeId ID = ShapeId.from("aws.endpoints#standardRegionalEndpoints");
47
    
48
    /**
49
     * Creates a new StandardRegionalEndpointsTrait with empty configuration
50
     */
51
    public StandardRegionalEndpointsTrait();
52
    
53
    /**
54
     * Creates a new StandardRegionalEndpointsTrait from object node
55
     * @param node Configuration object node
56
     */
57
    public StandardRegionalEndpointsTrait(ObjectNode node);
58
    
59
    /**
60
     * Trait provider for service registration
61
     */
62
    public static final class Provider extends AnnotationTrait.Provider<StandardRegionalEndpointsTrait> {
63
        public Provider();
64
    }
65
}
66
```
67

68
#### StandardPartitionalEndpointsTrait
69
```java { .api }
70
/**
71
 * A trait that indicates a service uses standard partitional endpoint patterns.
72
 */
73
public final class StandardPartitionalEndpointsTrait extends AnnotationTrait {
74
    /** Trait shape ID */  
75
    public static final ShapeId ID = ShapeId.from("aws.endpoints#standardPartitionalEndpoints");
76
    
77
    /**
78
     * Creates a new StandardPartitionalEndpointsTrait with empty configuration
79
     */
80
    public StandardPartitionalEndpointsTrait();
81
    
82
    /**
83
     * Creates a new StandardPartitionalEndpointsTrait from object node
84
     * @param node Configuration object node
85
     */
86
    public StandardPartitionalEndpointsTrait(ObjectNode node);
87
    
88
    /**
89
     * Trait provider for service registration
90
     */
91
    public static final class Provider extends AnnotationTrait.Provider<StandardPartitionalEndpointsTrait> {
92
        public Provider();
93
    }
94
}
95
```
96

97
#### DualStackOnlyEndpointsTrait
98
```java { .api }
99
/**
100
 * A trait that indicates that a service only supports dual-stack endpoints.
101
 */
102
public final class DualStackOnlyEndpointsTrait extends AnnotationTrait {
103
    /** Trait shape ID */
104
    public static final ShapeId ID = ShapeId.from("aws.endpoints#dualStackOnlyEndpoints");
105
    
106
    /**
107
     * Creates a new DualStackOnlyEndpointsTrait with empty configuration
108
     */
109
    public DualStackOnlyEndpointsTrait();
110
    
111
    /**
112
     * Creates a new DualStackOnlyEndpointsTrait from object node
113
     * @param node Configuration object node
114
     */
115
    public DualStackOnlyEndpointsTrait(ObjectNode node);
116
    
117
    /**
118
     * Trait provider for service registration
119
     */
120
    public static final class Provider extends AnnotationTrait.Provider<DualStackOnlyEndpointsTrait> {
121
        public Provider();
122
    }
123
}
124
```
125

126
### Endpoint Modification Traits
127

128
#### EndpointModifierTrait
129
```java { .api }
130
/**
131
 * A trait for modifying endpoint behavior with patterns and special cases.
132
 */
133
public final class EndpointModifierTrait extends AbstractTrait {
134
    /** Trait shape ID */
135
    public static final ShapeId ID = ShapeId.from("aws.endpoints#endpointModifier");
136
    
137
    /**
138
     * Creates a new EndpointModifierTrait from builder
139
     * @param builder Trait builder
140
     */
141
    public EndpointModifierTrait(Builder builder);
142
    
143
    /**
144
     * Gets the endpoint pattern type
145
     * @return Endpoint pattern type
146
     */
147
    public EndpointPatternType getPattern();
148
    
149
    /**
150
     * Gets the special case configurations
151
     * @return List of special cases
152
     */
153
    public List<PartitionSpecialCase> getSpecialCases();
154
    
155
    /**
156
     * Creates a builder for this trait
157
     * @return New builder instance
158
     */
159
    public static Builder builder();
160
    
161
    /**
162
     * Converts this trait to a builder
163
     * @return Builder with current trait values
164
     */
165
    public Builder toBuilder();
166
    
167
    /**
168
     * Builder for EndpointModifierTrait
169
     */
170
    public static final class Builder extends AbstractTraitBuilder<EndpointModifierTrait, Builder> {
171
        /**
172
         * Sets the endpoint pattern type
173
         * @param pattern Endpoint pattern type
174
         * @return This builder
175
         */
176
        public Builder pattern(EndpointPatternType pattern);
177
        
178
        /**
179
         * Sets the special cases
180
         * @param specialCases List of special cases
181
         * @return This builder
182
         */
183
        public Builder specialCases(List<PartitionSpecialCase> specialCases);
184
        
185
        /**
186
         * Adds a special case
187
         * @param specialCase Special case to add
188
         * @return This builder
189
         */
190
        public Builder addSpecialCase(PartitionSpecialCase specialCase);
191
        
192
        /**
193
         * Builds the trait
194
         * @return EndpointModifierTrait instance
195
         */
196
        public EndpointModifierTrait build();
197
    }
198
    
199
    /**
200
     * Trait provider for service registration
201
     */
202
    public static final class Provider extends AbstractTrait.Provider {
203
        public Provider();
204
    }
205
}
206
```
207

208
### DualStackOnlyEndpointsTrait
209

210
An annotation trait that indicates a service has only dual stack endpoints and does not support IPv4-only endpoints.
211

212
```java { .api }
213
/**
214
 * An endpoints modifier trait that indicates a service has only dual stack endpoints,
215
 * does not support IPV4 only endpoints, and should not have the useDualStackEndpoint endpoint parameter.
216
 */
217
public final class DualStackOnlyEndpointsTrait extends AnnotationTrait {
218
    public static final ShapeId ID = ShapeId.from("aws.endpoints#dualStackOnlyEndpoints");
219
    
220
    /**
221
     * Creates a DualStackOnlyEndpointsTrait from a node
222
     * @param node The object node
223
     */
224
    public DualStackOnlyEndpointsTrait(ObjectNode node);
225
    
226
    /**
227
     * Creates a DualStackOnlyEndpointsTrait with default configuration
228
     */
229
    public DualStackOnlyEndpointsTrait();
230
    
231
    /**
232
     * Trait provider for service registration
233
     */
234
    public static final class Provider extends AnnotationTrait.Provider<DualStackOnlyEndpointsTrait> {
235
        public Provider();
236
    }
237
}
238
```
239

240
### StandardPartitionalEndpointsTrait
241

242
A trait that indicates that a service is partitional and a single endpoint should resolve per partition.
243

244
```java { .api }
245
/**
246
 * An endpoints modifier trait that indicates that a service is partitional
247
 * and a single endpoint should resolve per partition.
248
 */
249
public final class StandardPartitionalEndpointsTrait extends AbstractTrait 
250
        implements ToSmithyBuilder<StandardPartitionalEndpointsTrait> {
251
    public static final ShapeId ID = ShapeId.from("aws.endpoints#standardPartitionalEndpoints");
252
    
253
    /**
254
     * Gets the map of partition string to a list of partition endpoint special cases
255
     * @return Map of partition string to list of PartitionEndpointSpecialCase
256
     */
257
    public Map<String, List<PartitionEndpointSpecialCase>> getPartitionEndpointSpecialCases();
258
    
259
    /**
260
     * Gets the endpoint pattern type defined in the trait
261
     * @return EndpointPatternType
262
     */
263
    public EndpointPatternType getEndpointPatternType();
264
    
265
    /**
266
     * Creates a builder for the trait
267
     * @return Builder instance
268
     */
269
    public static Builder builder();
270
    
271
    /**
272
     * Builder for StandardPartitionalEndpointsTrait
273
     */
274
    public static final class Builder extends AbstractTraitBuilder<StandardPartitionalEndpointsTrait, Builder> {
275
        /**
276
         * Sets the partition endpoint special cases
277
         * @param partitionEndpointSpecialCases Map of partition string to list of PartitionEndpointSpecialCase
278
         * @return This builder
279
         */
280
        public Builder partitionEndpointSpecialCases(
281
            Map<String, List<PartitionEndpointSpecialCase>> partitionEndpointSpecialCases);
282
        
283
        /**
284
         * Sets partition endpoint special cases for a specific partition
285
         * @param partition The partition name
286
         * @param partitionEndpointSpecialCases List of PartitionEndpointSpecialCase
287
         * @return This builder
288
         */
289
        public Builder putPartitionEndpointSpecialCase(
290
            String partition, 
291
            List<PartitionEndpointSpecialCase> partitionEndpointSpecialCases);
292
        
293
        /**
294
         * Sets the endpoint pattern type
295
         * @param endpointPatternType The endpoint pattern type
296
         * @return This builder
297
         */
298
        public Builder endpointPatternType(EndpointPatternType endpointPatternType);
299
        
300
        /**
301
         * Builds the trait
302
         * @return StandardPartitionalEndpointsTrait instance
303
         */
304
        public StandardPartitionalEndpointsTrait build();
305
    }
306
    
307
    /**
308
     * Trait provider for service registration
309
     */
310
    public static final class Provider extends AbstractTrait.Provider {
311
        public Provider();
312
    }
313
}
314
```
315

316
### Supporting Types and Enums
317

318
#### EndpointPatternType
319
```java { .api }
320
/**
321
 * Enum for endpoint pattern types
322
 */
323
public enum EndpointPatternType {
324
    /** Regional endpoint pattern */
325
    REGIONAL,
326
    
327
    /** Partitional endpoint pattern */  
328
    PARTITIONAL,
329
    
330
    /** Global endpoint pattern */
331
    GLOBAL;
332
    
333
    /**
334
     * Gets the enum value from string
335
     * @param value String representation
336
     * @return EndpointPatternType value
337
     */
338
    public static EndpointPatternType fromString(String value);
339
    
340
    /**
341
     * Gets the string representation
342
     * @return String value
343
     */
344
    public String toString();
345
}
346
```
347

348
#### Special Case Classes
349
```java { .api }
350
/**
351
 * Special case configuration for partitions
352
 */
353
public final class PartitionSpecialCase {
354
    /**
355
     * Gets the partition name this special case applies to
356
     * @return Partition name
357
     */
358
    public String getPartition();
359
    
360
    /**
361
     * Gets the endpoint special cases for this partition
362
     * @return List of partition endpoint special cases
363
     */
364
    public List<PartitionEndpointSpecialCase> getEndpoints();
365
    
366
    /**
367
     * Creates a builder for PartitionSpecialCase
368
     * @return New builder instance
369
     */
370
    public static Builder builder();
371
}
372

373
/**
374
 * Special case configuration for specific regions
375
 */
376
public final class RegionSpecialCase {
377
    /**
378
     * Gets the region this special case applies to
379
     * @return Region name
380
     */
381
    public String getRegion();
382
    
383
    /**
384
     * Gets the endpoint override for this region
385
     * @return Endpoint override configuration
386
     */
387
    public String getEndpoint();
388
    
389
    /**
390
     * Creates a builder for RegionSpecialCase
391
     * @return New builder instance
392
     */
393
    public static Builder builder();
394
}
395

396
/**
397
 * Special case configuration for partition endpoints
398
 */
399
public final class PartitionEndpointSpecialCase {
400
    /**
401
     * Gets the endpoint template
402
     * @return Endpoint template string
403
     */
404
    public String getEndpoint();
405
    
406
    /**
407
     * Gets whether dual-stack is supported
408
     * @return true if dual-stack is supported
409
     */
410
    public boolean isDualStack();
411
    
412
    /**
413
     * Gets whether FIPS is supported  
414
     * @return true if FIPS is supported
415
     */
416
    public boolean isFips();
417
    
418
    /**
419
     * Creates a builder for PartitionEndpointSpecialCase
420
     * @return New builder instance
421
     */
422
    public static Builder builder();
423
}
424
```
425

426
### Endpoint Index
427

428
#### EndpointModifierIndex
429
```java { .api }
430
/**
431
 * Index for accessing endpoint modifier traits across models
432
 */
433
public final class EndpointModifierIndex implements KnowledgeIndex {
434
    /**
435
     * Creates an index from a model
436
     * @param model Smithy model to index
437
     * @return EndpointModifierIndex instance
438
     */
439
    public static EndpointModifierIndex of(Model model);
440
    
441
    /**
442
     * Gets the endpoint modifier trait for a shape
443
     * @param shapeId Shape to get modifier for
444
     * @return Optional containing the modifier trait, or empty if not present
445
     */
446
    public Optional<EndpointModifierTrait> getEndpointModifier(ToShapeId shapeId);
447
    
448
    /**
449
     * Gets all shapes with endpoint modifier traits
450
     * @return Map of shape IDs to their endpoint modifier traits
451
     */
452
    public Map<ShapeId, EndpointModifierTrait> getAllEndpointModifiers();
453
}
454
```
455

456
**Usage Examples:**
457

458
```java
459
import software.amazon.smithy.rulesengine.aws.traits.*;
460
import software.amazon.smithy.model.shapes.ServiceShape;
461

462
// Apply rule-based endpoints trait to a service
463
ServiceShape service = ServiceShape.builder()
464
    .id("com.example#MyService")
465
    .addTrait(new RuleBasedEndpointsTrait())
466
    .build();
467

468
// Apply standard regional endpoints trait
469
ServiceShape regionalService = ServiceShape.builder()
470
    .id("com.example#RegionalService") 
471
    .addTrait(new StandardRegionalEndpointsTrait())
472
    .build();
473

474
// Apply dual-stack only trait
475
ServiceShape dualStackService = ServiceShape.builder()
476
    .id("com.example#DualStackService")
477
    .addTrait(new DualStackOnlyEndpointsTrait())
478
    .build();
479

480
// Create endpoint modifier with special cases
481
EndpointModifierTrait endpointModifier = EndpointModifierTrait.builder()
482
    .pattern(EndpointPatternType.REGIONAL)
483
    .addSpecialCase(
484
        PartitionSpecialCase.builder()
485
            .partition("aws-us-gov")
486
            .addEndpoint(
487
                PartitionEndpointSpecialCase.builder()
488
                    .endpoint("service.{region}.amazonaws.com")
489
                    .fips(true)
490
                    .dualStack(false)
491
                    .build()
492
            )
493
            .build()
494
    )
495
    .build();
496

497
// Use endpoint modifier index
498
EndpointModifierIndex index = EndpointModifierIndex.of(model);
499
Optional<EndpointModifierTrait> modifier = index.getEndpointModifier(serviceId);
500
```
501

502
## Trait Applications
503

504
### Service-Level Traits
505

506
Applied to service shapes to declare endpoint behavior:
507

508
```smithy
509
@aws.endpoints#rulesBasedEndpoints
510
service MyCustomService {}
511

512
@aws.endpoints#standardRegionalEndpoints  
513
service StandardService {}
514

515
@aws.endpoints#dualStackOnlyEndpoints
516
service IPv6OnlyService {}
517
```
518

519
### Endpoint Pattern Configuration
520

521
```smithy
522
@aws.endpoints#endpointModifier(
523
    pattern: "regional",
524
    specialCases: [
525
        {
526
            partition: "aws-us-gov",
527
            endpoints: [
528
                {
529
                    endpoint: "service.{region}.amazonaws.com",
530
                    fips: true,
531
                    dualStack: false
532
                }
533
            ]
534
        }
535
    ]
536
)
537
service ConfigurableService {}
538
```
539

540
## Service Registration
541

542
All traits are automatically registered through the Java Service Provider Interface:
543

544
```
545
META-INF/services/software.amazon.smithy.model.traits.TraitService
546
```
547

548
The registration includes:
549
- `RuleBasedEndpointsTrait$Provider`
550
- `StandardRegionalEndpointsTrait$Provider`
551
- `StandardPartitionalEndpointsTrait$Provider`
552
- `DualStackOnlyEndpointsTrait$Provider`
553
- `EndpointModifierTrait$Provider`
554

555
## Integration with Endpoint Rules
556

557
These traits work with the Smithy rules engine to:
558

559
1. **Declare Endpoint Behavior**: Specify how services should construct endpoints
560
2. **Configure Special Cases**: Handle partition-specific endpoint variations
561
3. **Enable Validation**: Ensure endpoint configurations are valid
562
4. **Support Code Generation**: Enable automatic endpoint resolution code generation