CLOUDP-306581: base types oneof

Author: wtrocki

tools/spectral/ipa/__tests__/IPA125OneOfNoBaseTypes.test.js

@@ -0,0 +1,109 @@
+import testRule from './__helpers__/testRule';
+import { DiagnosticSeverity } from '@stoplight/types';
+
+const componentSchemas = {
+  schemas: {
+    Dog: {
+      type: 'object',
+      properties: {
+        breed: { type: 'string' },
+        age: { type: 'integer' },
+      },
+    },
+    Cat: {
+      type: 'object',
+      properties: {
+        color: { type: 'string' },
+        livesLeft: { type: 'integer' },
+      },
+    },
+  },
+};
+
+testRule('xgen-IPA-125-oneOf-no-base-types', [
+  {
+    name: 'valid oneOf with references only',
+    document: {
+      components: componentSchemas,
+      schemas: {
+        Animal: {
+          oneOf: [{ $ref: '#/components/schemas/Dog' }, { $ref: '#/components/schemas/Cat' }],
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'valid oneOf with object schema',
+    document: {
+      components: componentSchemas,
+      schemas: {
+        MixedObject: {
+          oneOf: [
+            {
+              type: 'object',
+              properties: {
+                name: { type: 'string' },
+              },
+            },
+            { $ref: '#/components/schemas/Dog' },
+          ],
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid oneOf with string type',
+    document: {
+      components: componentSchemas,
+      schemas: {
+        MixedType: {
+          oneOf: [{ type: 'string' }, { $ref: '#/components/schemas/Dog' }],
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-125-oneOf-no-base-types',
+        message: 'oneOf should not contain base types like integer, number, string, or boolean.',
+        path: ['schemas', 'MixedType'],
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'invalid oneOf with multiple base types',
+    document: {
+      components: componentSchemas,
+      schemas: {
+        BaseTypes: {
+          oneOf: [{ type: 'string' }, { type: 'integer' }, { type: 'boolean' }],
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-125-oneOf-no-base-types',
+        message: 'oneOf should not contain base types like integer, number, string, or boolean.',
+        path: ['schemas', 'BaseTypes'],
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'oneOf with exception',
+    document: {
+      components: componentSchemas,
+      schemas: {
+        MixedType: {
+          oneOf: [{ type: 'string' }, { type: 'integer' }],
+          'x-xgen-IPA-exception': {
+            'xgen-IPA-125-oneOf-no-base-types': 'reason for exemption',
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+]);

tools/spectral/ipa/rulesets/IPA-125.yaml

@@ -3,6 +3,7 @@
 
 functions:
   - IPA125OneOfMustHaveDiscriminator
+  - IPA125OneOfNoBaseTypes
 
 rules:
   xgen-IPA-125-oneOf-must-have-discriminator:
@@ -39,3 +40,51 @@ rules:
     given: '$..[?(@.oneOf)]'
     then:
       function: 'IPA125OneOfMustHaveDiscriminator'
+
+  xgen-IPA-125-oneOf-no-base-types:
+    description: |
+      API producers should not use oneOf with base types like integer, string, boolean, or number.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies to schemas with `oneOf` arrays
+        - Ensures no element within oneOf has a type property that is a primitive/base type
+        - Base types considered are: integer, string, boolean, number
+
+      ##### Rationale
+      Using oneOf with primitive types can lead to ambiguity and validation problems. Clients may not 
+      be able to properly determine which type to use in which context. Instead, use more specific 
+      object types with clear discriminators.
+
+      ##### Example Violation
+      ```yaml
+      # Incorrect - Using oneOf with base types
+      type: object
+      properties:
+        value:
+          oneOf:
+            - type: string
+            - type: integer
+      ```
+
+      ##### Example Compliance
+      ```yaml
+      # Correct - Using oneOf with object types only
+      type: object
+      properties:
+        value:
+          oneOf:
+            - $ref: '#/components/schemas/StringValue'
+            - $ref: '#/components/schemas/IntegerValue'
+          discriminator:
+            propertyName: valueType
+            mapping:
+              string: '#/components/schemas/StringValue'
+              integer: '#/components/schemas/IntegerValue'
+      ```
+
+    message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-125-oneOf-no-base-types'
+    severity: error
+    given: '$..[?(@.oneOf)]'
+    then:
+      function: 'IPA125OneOfNoBaseTypes'

tools/spectral/ipa/rulesets/functions/IPA125OneOfNoBaseTypes.js

@@ -0,0 +1,32 @@
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
+import { resolveObject } from './utils/componentUtils.js';
+import { hasException } from './utils/exceptions.js';
+
+const RULE_NAME = 'xgen-IPA-125-oneOf-no-base-types';
+const ERROR_MESSAGE = 'oneOf should not contain base types like integer, number, string, or boolean.';
+
+export default (input, _, { path, documentInventory }) => {
+  const oas = documentInventory.unresolved; // Use unresolved document to access raw $ref
+  const schema = resolveObject(oas, path);
+
+  if (!schema || !schema.oneOf || !Array.isArray(schema.oneOf)) {
+    return;
+  }
+
+  // Check for exception first
+  if (hasException(schema, RULE_NAME)) {
+    return;
+  }
+
+  // Check if any oneOf item is a base type
+  const baseTypes = ['integer', 'number', 'string', 'boolean'];
+  const hasBaseType = schema.oneOf.some(
+    (item) => typeof item === 'object' && item.type && baseTypes.includes(item.type)
+  );
+
+  if (hasBaseType) {
+    return collectAndReturnViolation(path, RULE_NAME, [{ message: ERROR_MESSAGE }]);
+  }
+
+  collectAdoption(path, RULE_NAME);
+};