Add common field name variants to AEP-143 detection

Author: shakrav2

docs/0143.md

@@ -18,15 +18,40 @@ for common concepts like languages, currencies, regions, and media types.
 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`              | IETF BCP-47      |
-| Country/Region     | `region_code`      | `country`, `country_code`       | Unicode CLDR     |
-| Currency           | `currency_code`    | `currency`                      | ISO-4217         |
-| Content/Media Type | `content_type`     | `mime`, `mimetype`, `mime_type` | IANA media types |
-| Time Zone          | `time_zone`        | `tz`, `timezone`                | IANA TZ          |
+| 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
 

functions/standardized-codes.js

@@ -7,14 +7,18 @@ const fieldNameVariants = {
   mime: 'content_type',
   mimetype: 'content_type',
   mime_type: 'content_type',
+  media_type: 'content_type',
+  mediatype: 'content_type',
   // Countries/Regions
   country: 'region_code',
   country_code: 'region_code',
+  region: 'region_code',
   // Currency
   currency: 'currency_code',
   // Language
   lang: 'language_code',
   language: 'language_code',
+  locale: 'language_code',
   // Time zones
   tz: 'time_zone',
   timezone: 'time_zone',

test/0143/standardized-codes.test.js

@@ -205,6 +205,106 @@ describe('aep-143-standardized-codes', () => {
     });
   });
 
+  test('should flag "region" and suggest "region_code"', () => {
+    const oasDoc = {
+      openapi: '3.0.3',
+      components: {
+        schemas: {
+          Address: {
+            type: 'object',
+            properties: {
+              region: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    };
+    return linter.run(oasDoc).then((results) => {
+      expect(results.length).toBe(1);
+      expect(results).toContainMatch({
+        path: ['components', 'schemas', 'Address', 'properties', 'region'],
+        message: 'Use "region_code" instead of "region" for standardized code fields.',
+      });
+    });
+  });
+
+  test('should flag "locale" and suggest "language_code"', () => {
+    const oasDoc = {
+      openapi: '3.0.3',
+      components: {
+        schemas: {
+          Book: {
+            type: 'object',
+            properties: {
+              locale: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    };
+    return linter.run(oasDoc).then((results) => {
+      expect(results.length).toBe(1);
+      expect(results).toContainMatch({
+        path: ['components', 'schemas', 'Book', 'properties', 'locale'],
+        message: 'Use "language_code" instead of "locale" for standardized code fields.',
+      });
+    });
+  });
+
+  test('should flag "media_type" and suggest "content_type"', () => {
+    const oasDoc = {
+      openapi: '3.0.3',
+      components: {
+        schemas: {
+          File: {
+            type: 'object',
+            properties: {
+              media_type: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    };
+    return linter.run(oasDoc).then((results) => {
+      expect(results.length).toBe(1);
+      expect(results).toContainMatch({
+        path: ['components', 'schemas', 'File', 'properties', 'media_type'],
+        message: 'Use "content_type" instead of "media_type" for standardized code fields.',
+      });
+    });
+  });
+
+  test('should flag "mediatype" and suggest "content_type"', () => {
+    const oasDoc = {
+      openapi: '3.0.3',
+      components: {
+        schemas: {
+          File: {
+            type: 'object',
+            properties: {
+              mediatype: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    };
+    return linter.run(oasDoc).then((results) => {
+      expect(results.length).toBe(1);
+      expect(results).toContainMatch({
+        path: ['components', 'schemas', 'File', 'properties', 'mediatype'],
+        message: 'Use "content_type" instead of "mediatype" for standardized code fields.',
+      });
+    });
+  });
+
   test('should not flag correct standardized field names', () => {
     const oasDoc = {
       openapi: '3.0.3',