Add linting rules for AEP-126: Enumerations

aep/0126.yaml

@@ -0,0 +1,73 @@
+functionsDir: ../functions
+functions:
+  - aep-126-enum-case-consistent
+
+aliases:
+  EnumProperty:
+    description: An enumerated property.
+    targets:
+      - formats: ['oas2', 'oas3']
+        given:
+          - $..[?(@property === 'enum')]^
+
+rules:
+  aep-126-enum-type-string:
+    description: Enumerated fields should use type string, not integer or other types.
+    message: Enum field "{{property}}" should have type "string", not "{{error}}".
+    severity: error
+    formats: ['oas2', 'oas3']
+    given: '#EnumProperty'
+    then:
+      field: type
+      function: schema
+      functionOptions:
+        schema:
+          oneOf:
+            - const: string
+            - type: array
+              contains:
+                const: string
+                # Exclude everything else but "null"
+                not:
+                  anyOf:
+                    - const: boolean
+                    - const: integer
+                    - const: number
+                    - const: object
+                    - const: array
+
+  aep-126-enum-case-consistent:
+    description: All enum values in a field should use consistent case format.
+    message: '{{error}}'
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given: '#EnumProperty'
+    then:
+      function: aep-126-enum-case-consistent
+
+  aep-126-no-standard-value-enums:
+    description: Fields should not enumerate standard codes (language, country, currency, media types).
+    severity: warn
+    formats: ['oas2', 'oas3']
+    given:
+      - $..properties[[?(@property == 'language' || @property == 'language_code')]]
+      - $..properties[[?(@property == 'country' || @property == 'country_code' || @property == 'region_code')]]
+      - $..properties[[?(@property == 'currency' || @property == 'currency_code')]]
+      - $..properties[[?(@property == 'media_type' || @property == 'content_type')]]
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          not:
+            required: ['enum']
+
+  aep-126-enum-has-description:
+    description: Enum fields should include a description explaining their purpose.
+    message: Enum field "{{property}}" should have a description.
+    severity: info
+    formats: ['oas2', 'oas3']
+    given: '#EnumProperty'
+    then:
+      field: description
+      function: truthy

docs/0126.md

@@ -0,0 +1,231 @@
+# Rules for AEP-126: Enumerations
+
+[aep-126]: https://aep.dev/126
+
+## aep-126-enum-type-string
+
+**Rule**: Enumerated fields should use `type: string`, not `type: integer` or
+other types.
+
+This rule enforces that all enum fields use string types for better readability
+and maintainability.
+
+### Details
+
+This rule checks that fields with an `enum` property have `type: string`.
+Integer or number enums are less readable and harder to maintain than string
+enums.
+
+### Examples
+
+**Incorrect** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Book:
+      type: object
+      properties:
+        status:
+          type: integer
+          enum: [0, 1, 2]
+```
+
+**Correct** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Book:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ['DRAFT', 'PUBLISHED', 'ARCHIVED']
+```
+
+### Disabling
+
+If you need to violate this rule, add an override:
+
+```yaml
+overrides:
+  - files:
+      - 'openapi.json#/components/schemas/Book/properties/status'
+    rules:
+      aep-126-enum-type-string: 'off'
+```
+
+## aep-126-enum-case-consistent
+
+**Rule**: All enum values in a field should use consistent case formatting.
+
+This rule ensures that all values within a single enum use the same case style
+(e.g., all UPPERCASE, all lowercase, or all kebab-case). It does not enforce a
+specific case format, only consistency.
+
+### Details
+
+This rule checks that enum values don't mix different case styles like
+UPPERCASE, lowercase, camelCase, or kebab-case within the same enum.
+
+### Examples
+
+**Incorrect** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ['active', 'PENDING', 'In_Progress'] # Mixed case styles
+```
+
+**Correct** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ['ACTIVE', 'PENDING', 'IN_PROGRESS'] # Consistent UPPERCASE
+```
+
+```yaml
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ['active', 'pending', 'in-progress'] # Consistent lowercase/kebab-case
+```
+
+### Disabling
+
+```yaml
+overrides:
+  - files:
+      - 'openapi.json#/components/schemas/Order/properties/status'
+    rules:
+      aep-126-enum-case-consistent: 'off'
+```
+
+## aep-126-no-standard-value-enums
+
+**Rule**: Fields should not enumerate standard codes (language, country,
+currency, media types).
+
+This rule warns when field names suggest they contain standard codes that
+should reference existing standards rather than creating limited enums.
+
+### Details
+
+Standard codes like language codes (ISO 639), country codes (ISO 3166),
+currency codes (ISO 4217), and media types (IANA) should not be enumerated.
+Using enums for these values can lead to lookup tables and integration issues.
+
+Field names that trigger this warning:
+
+- `language`, `language_code` → Use ISO 639
+- `country`, `country_code`, `region_code` → Use ISO 3166
+- `currency`, `currency_code` → Use ISO 4217
+- `media_type`, `content_type` → Use IANA media types
+
+### Examples
+
+**Incorrect** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Document:
+      type: object
+      properties:
+        language:
+          type: string
+          enum: ['EN', 'FR', 'ES'] # Should use ISO 639 standard
+```
+
+**Correct** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Document:
+      type: object
+      properties:
+        language_code:
+          type: string
+          description: 'ISO 639-1 language code'
+          pattern: '^[a-z]{2}(-[A-Z]{2})?$'
+          example: 'en-US'
+```
+
+### Disabling
+
+```yaml
+overrides:
+  - files:
+      - 'openapi.json#/components/schemas/Document/properties/language'
+    rules:
+      aep-126-no-standard-value-enums: 'off'
+```
+
+## aep-126-enum-has-description
+
+**Rule**: Enum fields should include a `description` property.
+
+This rule encourages documentation of enum fields to help API consumers
+understand their purpose and usage.
+
+### Details
+
+Enum fields should include a description explaining what the enum represents
+and how it should be used.
+
+### Examples
+
+**Incorrect** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Book:
+      type: object
+      properties:
+        format:
+          type: string
+          enum: ['HARDCOVER', 'PAPERBACK', 'EBOOK'] # Missing description
+```
+
+**Correct** code for this rule:
+
+```yaml
+components:
+  schemas:
+    Book:
+      type: object
+      properties:
+        format:
+          type: string
+          description: 'The format in which the book is published'
+          enum: ['HARDCOVER', 'PAPERBACK', 'EBOOK', 'AUDIOBOOK']
+```
+
+### Disabling
+
+```yaml
+overrides:
+  - files:
+      - 'openapi.json#/components/schemas/Book/properties/format'
+    rules:
+      aep-126-enum-has-description: 'off'
+```

docs/rules.md

@@ -2,6 +2,7 @@
 
 - [Rules for AEP-4](./0004.md)
 - [Rules for AEP-122](./0122.md)
+- [Rules for AEP-126](./0126.md)
 - [Rules for AEP-131](./0131.md)
 - [Rules for AEP-132](./0132.md)
 - [Rules for AEP-133](./0133.md)