Implement rules for AEP-126: Enumerations

[shakrav2]

Implement linting rules for AEP-126 (Enumerations) to validate enum field usage in OpenAPI specs. This will ensure consistent enum patterns across APIs including proper type usage, case formatting, and handling of standard value codes.

Rules to Implement

• aep-126-enum-type-string: Enumerated fields should use type: string
• aep-126-enum-case-consistent: All enum values in a field should use consistent case format
• aep-126-enum-null-first: If enum is nullable, null should be the first value
• aep-126-enum-nullable-declaration: If enum contains null, field must have nullable: true
• aep-126-no-standard-value-enums: Warn against enumerating standard codes (language, country, currency, media types)
• aep-126-enum-has-description: Enums should include a description field

Details

aep-126-enum-type-string

Severity: error

Check that fields with enum property use type: string rather than type: integer or other types.

Rationale: String enums are more readable and maintainable than integer enums.

aep-126-enum-case-consistent

Severity: warn

Validate that all values within a single enum use the same case format (e.g., all UPPERCASE, all lowercase, or all kebab-case). This rule does not enforce a specific case style, only consistency.

Rationale: Consistent case formatting improves readability and reduces errors.

aep-126-enum-null-first

Severity: warn

For optional enums (fields with nullable: true), check that null is the first value in the enum array.

Rationale: Following a consistent pattern for null values improves API predictability.

aep-126-enum-nullable-declaration

Severity: error

If an enum array contains null as a value, verify that the field also declares nullable: true.

Rationale: This is required by OpenAPI 3.0 specification for proper validation.

aep-126-no-standard-value-enums

Severity: warn

Warn when field names suggest standard codes that should not be enumerated:

• language, language_code → Use ISO 639 language codes
• country, country_code, region_code → Use ISO 3166 country codes
• currency, currency_code → Use ISO 4217 currency codes
• media_type, content_type → Use IANA media types

Rationale: Standard codes should reference existing standards rather than creating limited enums, which can lead to lookup tables and integration issues.

aep-126-enum-has-description

Severity: info

Check that enum fields include a description property explaining the purpose and expected values.

Rationale: Documentation helps API consumers understand the enum's purpose and usage.

Acceptance Criteria

• All 6 rules implemented in aep/0126.yaml
• Custom functions created (if needed) in functions/
• Tests written for each rule in test/0126/
• Documentation added in docs/0126.md
• Rules added to spectral.yaml
• All tests passing (npm test)
• Code coverage > 80% for any custom functions
• Code follows project style guide (npm run lint)

Reference

• AEP Spec: https://aep.dev/126
• Contributing Guide: See CONTRIBUTING.md