feat: flag properties with the same name but different type (#140)

This is to catch properties used inconsistently throughout an API Definition

Author: presto21

README.md

@@ -262,6 +262,7 @@ The supported rules are described below:
 | no_property_description     | Flag any schema that contains a 'property' without a `description` field.     | shared   |
 | description_mentions_json   | Flag any schema with a 'property' description that mentions the word 'JSON'.  | shared   |
 | array_of_arrays             | Flag any schema with a 'property' of type `array` with items of type `array`. | shared   |
+| inconsistent_property_type  | Flag any properties that have the same name but an inconsistent type.         | shared   |
 | property_case_convention    | Flag any property with a `name` that does not follow a given case convention. snake_case_only must be 'off' to use. | shared |
 | enum_case_convention        | Flag any enum with a `value` that does not follow a given case convention. snake_case_only must be 'off' to use.    | shared |
 | json_or_param_binary_string | Flag parameters or application/json request/response bodies with schema type: string, format: binary. | oas3 |
@@ -440,6 +441,7 @@ The default values for each rule are described below.
 | no_property_description     | warning |
 | description_mentions_json   | warning |
 | array_of_arrays             | warning |
+| inconsistent_property_type  | warning |
 | property_case_convention    | error, lower_snake_case |
 | enum_case_convention        | error, lower_snake_case |
 

src/.defaultsForValidator.js

@@ -64,6 +64,7 @@ const defaults = {
       'no_property_description': 'warning',
       'description_mentions_json': 'warning',
       'array_of_arrays': 'warning',
+      'inconsistent_property_type': 'warning',
       'property_case_convention': [ 'error', 'lower_snake_case'],
       'enum_case_convention': [ 'error', 'lower_snake_case']
     },

src/plugins/validation/2and3/semantic-validators/schema-ibm.js

@@ -100,6 +100,10 @@ module.exports.validate = function({ jsSpec, isOAS3 }, config) {
     }
   });
 
+  // Collect the properties info. Pass it to checkProperties to catch
+  // properties that have the same name but an inconsistent type.
+  const propertiesToCompare = {};
+
   schemas.forEach(({ schema, path }) => {
     generateFormatErrors(schema, path, config, isOAS3, messages);
 
@@ -137,6 +141,15 @@ module.exports.validate = function({ jsSpec, isOAS3 }, config) {
         }
       }
     }
+    if (config.inconsistent_property_type !== 'off') {
+      checkProperties(
+        schema,
+        propertiesToCompare,
+        path,
+        config.inconsistent_property_type,
+        messages
+      );
+    }
   });
 
   return messages;
@@ -511,3 +524,44 @@ function isRootSchema(path) {
     current === 'schema' || (parent === 'definitions' && path.length === 2)
   );
 }
+
+// Flag any properties that have the same name but an inconsistent type.
+function checkProperties(
+  schema,
+  propertiesToCompare,
+  contextPath,
+  configOption,
+  messages
+) {
+  if (!schema.properties) return;
+
+  for (const [key, value] of Object.entries(schema.properties)) {
+    // skips properties that use $ref
+    if (value.type) {
+      if (propertiesToCompare[key]) {
+        if (propertiesToCompare[key].type !== value.type) {
+          // First property that appeared in API def, should only print once.
+          if (!propertiesToCompare[key].printed) {
+            propertiesToCompare[key].printed = true;
+            messages.addMessage(
+              propertiesToCompare[key].path,
+              `Property has inconsistent type: ${key}.`,
+              configOption
+            );
+          }
+          messages.addMessage(
+            contextPath.concat(['properties', key]).join('.'),
+            `Property has inconsistent type: ${key}.`,
+            configOption
+          );
+        }
+      } else {
+        propertiesToCompare[key] = {
+          type: value.type,
+          path: contextPath.concat(['properties', key]).join('.'),
+          printed: false
+        };
+      }
+    }
+  }
+}

test/plugins/validation/2and3/schema-ibm.js

@@ -1660,4 +1660,59 @@ describe('validation plugin - semantic - schema-ibm - OpenAPI 3', () => {
     expect(res.errors.length).toEqual(0);
     expect(res.warnings.length).toEqual(0);
   });
+
+  it('should produce a warning for properties that have the same name but an inconsistent type', () => {
+    const spec = {
+      components: {
+        schemas: {
+          person: {
+            description: 'Produce warnings',
+            properties: {
+              name: {
+                description: 'type integer',
+                type: 'integer'
+              }
+            }
+          },
+          adult: {
+            description: 'Causes first warnings',
+            properties: {
+              name: {
+                description: 'different type',
+                type: 'number'
+              }
+            }
+          },
+          kid: {
+            description: 'Causes second warning',
+            properties: {
+              name: {
+                type: 'string',
+                description: 'differnt type'
+              }
+            }
+          }
+        }
+      }
+    };
+
+    const message = 'Property has inconsistent type: name.';
+    const res = validate({ jsSpec: spec }, config);
+
+    expect(res.warnings.length).toEqual(3);
+    expect(res.errors.length).toEqual(0);
+
+    expect(res.warnings[0].message).toEqual(message);
+    expect(res.warnings[0].path).toEqual(
+      'components.schemas.person.properties.name'
+    );
+    expect(res.warnings[1].message).toEqual(message);
+    expect(res.warnings[1].path).toEqual(
+      'components.schemas.adult.properties.name'
+    );
+    expect(res.warnings[2].message).toEqual(message);
+    expect(res.warnings[2].path).toEqual(
+      'components.schemas.kid.properties.name'
+    );
+  });
 });