docs

Author: wtrocki

tools/spectral/ipa/rulesets/README.md

@@ -527,6 +527,24 @@ Rule checks for the following conditions:
 
 Rules are based on [http://go/ipa/IPA-125](http://go/ipa/IPA-125).
 
+#### xgen-IPA-125-oneOf-no-base-types
+
+ ![error](https://img.shields.io/badge/error-red) 
+API producers should not use oneOf with different base types like integer, string, boolean, or number or references at the same time.
+
+##### Implementation details
+Rule checks for the following conditions:
+  - Applies to schemas with `oneOf` arrays
+  - Ensures no mixing of base types with references
+  - Ensures no multiple different base types in the same oneOf
+  - Base types considered are: integer, string, boolean, number
+  - Using the same base type multiple times is allowed (e.g., multiple string enums)
+
+##### Rationale
+Using oneOf with multiple 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.
+
 #### xgen-IPA-125-oneOf-must-have-discriminator
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
@@ -557,49 +575,6 @@ Rule checks for the following conditions:
   ```
   This is valid because there are exactly 2 mappings for 2 oneOf references, and all values match.
 
-#### xgen-IPA-125-oneOf-no-base-types
-
- ![warn](https://img.shields.io/badge/warning-yellow) 
-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'
-```
-