Skip to content

Add linting rules for AEP-126: Enumerations #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add linting rules for AEP-126: Enumerations #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
196ba23
Add AEP-126 linting rules
shakrav2 Oct 19, 2025
2f3e3ae
Add field names and OpenAPI 3.1 support to AEP-126 nullable enum rules
shakrav2 Oct 23, 2025
0ecafa4
Fix Prettier formatting and ESLint line-length violations
shakrav2 Oct 31, 2025
b3b89b0
Fix aep-126-enum-type-string to support OAS 3.1 type arrays
shakrav2 Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions aep/0126.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
functionsDir: ../functions
functions:
- aep-126-enum-case-consistent
- aep-126-enum-null-first
- aep-126-enum-nullable-declaration
- aep-126-no-standard-value-enums

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: $..[?(@property === 'enum')]^
Copy link
Contributor

@mkistler mkistler Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is used in multiple givens, it seems like a good candidate for an alias.

then:
field: type
function: schema
functionOptions:
schema:
oneOf:
- const: string
- type: array
contains:
const: string
maxItems: 2
Copy link
Contributor

@mkistler mkistler Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess maxItems is here to allow "null" but it also allows other things that we'd want to flag. E.g. 'type: ["string", "number"]` should fail but I think would not currently.


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: $..[?(@property === 'enum')]^
then:
function: aep-126-enum-case-consistent

aep-126-enum-null-first:
description: If enum is nullable, null should be the first value in the enum array.
message: '{{error}}'
severity: warn
formats: ['oas2', 'oas3']
Copy link
Contributor

@mkistler mkistler Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no good way to represent "nullable" fields in oas2, so I think any rule that involves nullable types should not declare that it works on oas2.

Suggested change
formats: ['oas2', 'oas3']
formats: ['oas3']

given: $..[?(@property === 'enum')]^
then:
function: aep-126-enum-null-first

aep-126-enum-nullable-declaration:
description: If enum contains null, field must declare nullable true.
message: '{{error}}'
severity: error
formats: ['oas2', 'oas3']
Copy link
Contributor

@mkistler mkistler Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
formats: ['oas2', 'oas3']
formats: ['oas3']

given: $..[?(@property === 'enum')]^
then:
function: aep-126-enum-nullable-declaration

aep-126-no-standard-value-enums:
description: Fields should not enumerate standard codes (language, country, currency, media types).
message: '{{error}}'
severity: warn
formats: ['oas2', 'oas3']
given: $..[?(@property === 'enum')]^
then:
function: aep-126-no-standard-value-enums
Comment on lines +54 to +61
Copy link
Contributor

@mkistler mkistler Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need a custom function here. I think we can write the rule this way and avoid custom js code.

Suggested change
aep-126-no-standard-value-enums:
description: Fields should not enumerate standard codes (language, country, currency, media types).
message: '{{error}}'
severity: warn
formats: ['oas2', 'oas3']
given: $..[?(@property === 'enum')]^
then:
function: aep-126-no-standard-value-enums
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: $..[?(@property === 'enum')]^
then:
field: description
function: truthy
Loading