AEP-0143 Linter Rules

Rules for AEP-143: Standardized codes

This document covers the linting rules for AEP-143, which provides guidance on using standardized codes for common concepts like languages, regions, currencies, and time zones.

aep-143-standardized-codes

Rule: Field names for standardized codes must follow AEP-143 conventions.

This rule enforces that field names use the correct standardized terminology for common concepts like languages, currencies, regions, and media types.

Details

This rule checks schema property names and flags incorrect variants, suggesting the correct standardized field name according to AEP-143.

Limitations

This rule uses a map-based detection approach that only catches explicitly listed field name variants. While it covers the most common incorrect naming patterns, it cannot detect all possible variations developers might use.

What this means:

✅ Catches common mistakes like lang, country, mime_type, etc.
❌ Won’t catch creative variations like user_locale, iso_country, or document_mime
✅ Low false positive rate - only flags known incorrect patterns
❌ May miss some non-standard field names that should use standardized codes

Why this approach:

Pattern-based detection (e.g., flagging any field containing “language” or “country”) would produce too many false positives. The map-based approach is intentionally conservative to maintain high precision.

Recommendation: Use this rule as a first-pass check, but rely on human code review to catch edge cases and uncommon field name variations. If you encounter a common variant that should be flagged, consider contributing it to the linter.

Field Name Standards

Concept	Correct Field Name	Incorrect Variants	Standard
Language	`language_code`	`lang`, `language`, `locale`	IETF BCP-47
Country/Region	`region_code`	`country`, `country_code`, `region`	Unicode CLDR
Currency	`currency_code`	`currency`	ISO-4217
Content/Media Type	`content_type`	`mime`, `mimetype`, `mime_type`, `media_type`, `mediatype`	IANA media types
Time Zone	`time_zone`	`tz`, `timezone`	IANA TZ

Examples

Incorrect code for this rule:

components:
  schemas:
    book:
      type: object
      properties:
        title:
          type: string
        lang: # Should be language_code
          type: string
        country: # Should be region_code
          type: string

Correct code for this rule:

components:
  schemas:
    book:
      type: object
      properties:
        title:
          type: string
        language_code:
          type: string
          description: IETF BCP-47 language code (e.g., en-US, de-CH)
        region_code:
          type: string
          description: Unicode CLDR region code (e.g., US, CH)

Disabling

If you need to violate this rule, add an override to your Spectral configuration:

overrides:
  - files:
      - 'openapi.json#/components/schemas/book'
    rules:
      aep-143-standardized-codes: 'off'

aep-143-standardized-codes-string-type

Rule: Standardized code fields must be of type string.

This rule enforces that all standardized code fields (language_code, region_code, currency_code, content_type, time_zone, utc_offset) use type string.

Details

According to AEP-143, standardized code fields must use the appropriate data type for standard codes (usually string), and should not use enums even if they only allow a small subset of possible values.

This rule checks the following fields:

language_code
region_code
currency_code
content_type
time_zone
utc_offset

Examples

Incorrect code for this rule:

components:
  schemas:
    book:
      type: object
      properties:
        language_code:
          type: integer # Wrong type
          description: Language code

Correct code for this rule:

components:
  schemas:
    book:
      type: object
      properties:
        language_code:
          type: string
          description: IETF BCP-47 language code (e.g., en-US, de-CH)

Disabling

If you need to violate this rule, add an override to your Spectral configuration:

overrides:
  - files:
      - 'openapi.json#/components/schemas/book/properties/language_code'
    rules:
      aep-143-standardized-codes-string-type: 'off'

References