oas 20.8.0 → 20.8.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## <small>20.8.2 (2023-05-04)</small>
+
+* feat: adding a broken skipped test, retaining soeme more jsonschema props ([94436b8](https://github.com/readmeio/oas/commit/94436b8))
+* feat: additional tweaks to json schema generation (#762) ([2bae3fe](https://github.com/readmeio/oas/commit/2bae3fe)), closes [#762](https://github.com/readmeio/oas/issues/762)
+* feat: additional tweaks to json schema mixed type handling (#761) ([57d4442](https://github.com/readmeio/oas/commit/57d4442)), closes [#761](https://github.com/readmeio/oas/issues/761)
+
+
+
+## <small>20.8.1 (2023-05-04)</small>
+
+* feat: additional tweaks to json schema mixed type handling (#761) ([57d4442](https://github.com/readmeio/oas/commit/57d4442)), closes [#761](https://github.com/readmeio/oas/issues/761)
+
+
+
 ## 20.8.0 (2023-05-03)
 
 * feat: improved support for mixed types and `nullable` (#760) ([5eff5c4](https://github.com/readmeio/oas/commit/5eff5c4)), closes [#760](https://github.com/readmeio/oas/issues/760)

package/dist/lib/helpers.d.ts

@@ -1 +1,3 @@
+import type { SchemaObject } from 'rmoas.types';
+export declare function hasSchemaType(schema: SchemaObject, discriminator: 'array' | 'object'): boolean;
 export declare function isPrimitive(val: unknown): boolean;

package/dist/lib/helpers.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isPrimitive = void 0;
+exports.isPrimitive = exports.hasSchemaType = void 0;
+function hasSchemaType(schema, discriminator) {
+    if (Array.isArray(schema.type)) {
+        return schema.type.includes(discriminator);
+    }
+    return schema.type === discriminator;
+}
+exports.hasSchemaType = hasSchemaType;
 function isPrimitive(val) {
     return typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean';
 }

package/dist/lib/openapi-to-json-schema.js

@@ -60,6 +60,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSchemaVersionString = void 0;
 var json_schema_merge_allof_1 = __importDefault(require("json-schema-merge-allof"));
 var jsonpointer_1 = __importDefault(require("jsonpointer"));
+var remove_undefined_objects_1 = __importDefault(require("remove-undefined-objects"));
 var RMOAS = __importStar(require("../rmoas.types"));
 var helpers_1 = require("./helpers");
 /**
@@ -203,8 +204,8 @@ function searchForExampleByPointer(pointer, examples) {
                 example = jsonpointer_1.default.get(schema, pointers[i]);
             }
             catch (err) {
-                // If the schema we're looking at is `{obj: null}` and our pointer if `/obj/propertyName`
-                // jsonpointer will throw an error. If that happens, we should silently catch and toss it
+                // If the schema we're looking at is `{obj: null}` and our pointer is `/obj/propertyName`
+                // `jsonpointer` will throw an error. If that happens, we should silently catch and toss it
                 // and return no example.
             }
             if (example !== undefined) {
@@ -326,29 +327,6 @@ function toJSONSchema(data, opts) {
                 });
             }
         }
-        // To ease some of the burden on our frontend having to juggle mixed types we're opting to
-        // transform them into a `oneOf`.
-        if ('type' in schema && Array.isArray(schema.type)) {
-            schema.type = Array.from(new Set(schema.type));
-            // If we have a `null` type but there's only two types present then we can remove `null` as
-            // an option and flag the whole schema as `nullable`.
-            if (schema.type.includes('null')) {
-                schema.type = schema.type.filter(function (t) { return t !== 'null'; });
-                schema.nullable = true;
-            }
-            if (schema.type.length === 1) {
-                schema.type = schema.type.shift();
-            }
-            else {
-                var mixedOneOf_1 = [];
-                schema.type.forEach(function (schemaType) {
-                    mixedOneOf_1.push(__assign(__assign({}, schema), { type: schemaType }));
-                });
-                schema = {
-                    oneOf: mixedOneOf_1,
-                };
-            }
-        }
         ['anyOf', 'oneOf'].forEach(function (polyType) {
             if (polyType in schema && Array.isArray(schema[polyType])) {
                 schema[polyType].forEach(function (item, idx) {
@@ -406,6 +384,110 @@ function toJSONSchema(data, opts) {
             // Whatever tooling that ingests the generated schema should handle it however it needs to.
         }
     }
+    if ('type' in schema) {
+        // `nullable` isn't a thing in JSON Schema but it was in OpenAPI 3.0 so we should retain and
+        // translate it into something that's compatible with JSON Schema.
+        if ('nullable' in schema) {
+            if (Array.isArray(schema.type)) {
+                schema.type.push('null');
+            }
+            else if (schema.type !== null && schema.type !== 'null') {
+                schema.type = [schema.type, 'null'];
+            }
+            delete schema.nullable;
+        }
+        if (schema.type === null) {
+            // `type: null` is possible in JSON Schema but we're translating it to a string version
+            // so we don't need to worry about asserting nullish types in our implementations of this
+            // generated schema.
+            schema.type = 'null';
+        }
+        else if (Array.isArray(schema.type)) {
+            if (schema.type.includes(null)) {
+                schema.type[schema.type.indexOf(null)] = 'null';
+            }
+            schema.type = Array.from(new Set(schema.type));
+            // We don't need `type: [<type>]` when we can just as easily make it `type: <type>`.
+            if (schema.type.length === 1) {
+                schema.type = schema.type.shift();
+            }
+            else if (schema.type.includes('array') || schema.type.includes('object')) {
+                // If we have a `null` type but there's only two types present then we can remove `null`
+                // as an option and flag the whole schema as `nullable`.
+                var isNullable_1 = schema.type.includes('null');
+                if (schema.type.length === 2 && isNullable_1) {
+                    // If this is `array | null` or `object | null` then we don't need to do anything.
+                }
+                else {
+                    // If this mixed type has non-primitives then we for convenience of our implementation
+                    // we're moving them into a `oneOf`.
+                    var nonPrimitives_1 = [];
+                    // Because we're moving an `array` and/or an `object` into a `oneOf` we also want to take
+                    // with it its specific properties that maybe present on our current schema.
+                    Object.entries({
+                        // json-schema.org/understanding-json-schema/reference/array.html
+                        array: [
+                            'additionalItems',
+                            'contains',
+                            'items',
+                            'maxContains',
+                            'maxItems',
+                            'minContains',
+                            'minItems',
+                            'prefixItems',
+                            'uniqueItems',
+                        ],
+                        // https://json-schema.org/understanding-json-schema/reference/object.html
+                        object: [
+                            'additionalProperties',
+                            'maxProperties',
+                            'minProperties',
+                            'nullable',
+                            'patternProperties',
+                            'properties',
+                            'propertyNames',
+                            'required',
+                        ],
+                    }).forEach(function (_a) {
+                        var _b, _c, _d, _e, _f, _g;
+                        var typeKey = _a[0], keywords = _a[1];
+                        if (!schema.type.includes(typeKey)) {
+                            return;
+                        }
+                        var reducedSchema = (0, remove_undefined_objects_1.default)({
+                            type: isNullable_1 ? [typeKey, 'null'] : typeKey,
+                            allowEmptyValue: (_b = schema.allowEmptyValue) !== null && _b !== void 0 ? _b : undefined,
+                            deprecated: (_c = schema.deprecated) !== null && _c !== void 0 ? _c : undefined,
+                            description: (_d = schema.description) !== null && _d !== void 0 ? _d : undefined,
+                            readOnly: (_e = schema.readOnly) !== null && _e !== void 0 ? _e : undefined,
+                            title: (_f = schema.title) !== null && _f !== void 0 ? _f : undefined,
+                            writeOnly: (_g = schema.writeOnly) !== null && _g !== void 0 ? _g : undefined,
+                        });
+                        keywords.forEach(function (t) {
+                            if (t in schema) {
+                                reducedSchema[t] = schema[t];
+                                delete schema[t];
+                            }
+                        });
+                        nonPrimitives_1.push(reducedSchema);
+                    });
+                    schema.type = schema.type.filter(function (t) { return t !== 'array' && t !== 'object'; });
+                    if (schema.type.length === 1) {
+                        schema.type = schema.type.shift();
+                    }
+                    // Because we may have encountered a fully mixed non-primitive type like `array | object`
+                    // we only want to retain the existing schema object if we still have types remaining
+                    // in it.
+                    if (schema.type.length > 1) {
+                        schema = { oneOf: __spreadArray([schema], nonPrimitives_1, true) };
+                    }
+                    else {
+                        schema = { oneOf: nonPrimitives_1 };
+                    }
+                }
+            }
+        }
+    }
     if (RMOAS.isSchema(schema, isPolymorphicAllOfChild)) {
         // JSON Schema doesn't support OpenAPI-style examples so we need to reshape them a bit.
         if ('example' in schema) {
@@ -471,7 +553,7 @@ function toJSONSchema(data, opts) {
         // If we didn't have any immediately defined examples, let's search backwards and see if we can
         // find one. But as we're only looking for primitive example, only try to search for one if
         // we're dealing with a primitive schema.
-        if (schema.type !== 'array' && schema.type !== 'object' && !schema.examples) {
+        if (!(0, helpers_1.hasSchemaType)(schema, 'array') && !(0, helpers_1.hasSchemaType)(schema, 'object') && !schema.examples) {
             var foundExample = searchForExampleByPointer(currentLocation, prevSchemas);
             if (foundExample) {
                 // We can only really deal with primitives, so only promote those as the found example if
@@ -481,7 +563,7 @@ function toJSONSchema(data, opts) {
                 }
             }
         }
-        if (schema.type === 'array') {
+        if ((0, helpers_1.hasSchemaType)(schema, 'array')) {
             if ('items' in schema) {
                 if (!Array.isArray(schema.items) && Object.keys(schema.items).length === 1 && RMOAS.isRef(schema.items)) {
                     // `items` contains a `$ref`, so since it's circular we should do a no-op here and log
@@ -505,17 +587,15 @@ function toJSONSchema(data, opts) {
                 // array. Since throwing a complete failure isn't ideal, we can see that they meant for the
                 // type to be `object`, so we can do our best to shape the data into what they were
                 // intending it to be.
-                // README-6R
                 schema.type = 'object';
             }
             else {
                 // This is a fix to handle cases where we have a malformed array with no `items` property
                 // present.
-                // README-8E
                 schema.items = {};
             }
         }
-        else if (schema.type === 'object') {
+        else if ((0, helpers_1.hasSchemaType)(schema, 'object')) {
             if ('properties' in schema) {
                 Object.keys(schema.properties).forEach(function (prop) {
                     if (Array.isArray(schema.properties[prop]) ||

package/dist/samples/index.js

@@ -85,7 +85,7 @@ function sampleFromSchema(schema, opts) {
             return undefined;
         }
     }
-    if (type === 'object') {
+    if (type === 'object' || (Array.isArray(type) && type.includes('object'))) {
         var props = (0, utils_1.objectify)(properties);
         var obj = {};
         // eslint-disable-next-line no-restricted-syntax
@@ -114,7 +114,7 @@ function sampleFromSchema(schema, opts) {
         }
         return obj;
     }
-    if (type === 'array') {
+    if (type === 'array' || (Array.isArray(type) && type.includes('array'))) {
         // `items` should always be present on arrays, but if it isn't we should at least do our best
         // to support its absence.
         if (typeof items === 'undefined') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "20.8.0",
+  "version": "20.8.2",
   "description": "Comprehensive tooling for working with OpenAPI definitions",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
@@ -54,7 +54,8 @@
     "memoizee": "^0.4.14",
     "oas-normalize": "^8.4.0",
     "openapi-types": "^12.1.0",
-    "path-to-regexp": "^6.2.0"
+    "path-to-regexp": "^6.2.0",
+    "remove-undefined-objects": "^2.0.2"
   },
   "devDependencies": {
     "@commitlint/cli": "^17.6.1",

package/src/lib/helpers.ts

@@ -1,3 +1,12 @@
+import type { SchemaObject } from 'rmoas.types';
+
+export function hasSchemaType(schema: SchemaObject, discriminator: 'array' | 'object') {
+  if (Array.isArray(schema.type)) {
+    return schema.type.includes(discriminator);
+  }
+
+  return schema.type === discriminator;
+}
 export function isPrimitive(val: unknown): boolean {
   return typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean';
 }

package/src/lib/openapi-to-json-schema.ts

@@ -1,12 +1,15 @@
 /* eslint-disable no-continue */
+import type { SchemaObject } from '../rmoas.types';
+import type { JSONSchema7TypeName } from 'json-schema';
 import type { OpenAPIV3_1 } from 'openapi-types';
 
 import mergeJSONSchemaAllOf from 'json-schema-merge-allof';
 import jsonpointer from 'jsonpointer';
+import removeUndefinedObjects from 'remove-undefined-objects';
 
 import * as RMOAS from '../rmoas.types';
 
-import { isPrimitive } from './helpers';
+import { hasSchemaType, isPrimitive } from './helpers';
 
 /**
  * This list has been pulled from `openapi-schema-to-json-schema` but been slightly modified to fit
@@ -205,8 +208,8 @@ function searchForExampleByPointer(pointer: string, examples: PrevSchemasType =
       try {
         example = jsonpointer.get(schema, pointers[i]);
       } catch (err) {
-        // If the schema we're looking at is `{obj: null}` and our pointer if `/obj/propertyName`
-        // jsonpointer will throw an error. If that happens, we should silently catch and toss it
+        // If the schema we're looking at is `{obj: null}` and our pointer is `/obj/propertyName`
+        // `jsonpointer` will throw an error. If that happens, we should silently catch and toss it
         // and return no example.
       }
 
@@ -362,35 +365,6 @@ export default function toJSONSchema(
       }
     }
 
-    // To ease some of the burden on our frontend having to juggle mixed types we're opting to
-    // transform them into a `oneOf`.
-    if ('type' in schema && Array.isArray(schema.type)) {
-      schema.type = Array.from(new Set(schema.type));
-
-      // If we have a `null` type but there's only two types present then we can remove `null` as
-      // an option and flag the whole schema as `nullable`.
-      if (schema.type.includes('null')) {
-        schema.type = schema.type.filter(t => t !== 'null');
-        schema.nullable = true;
-      }
-
-      if (schema.type.length === 1) {
-        schema.type = schema.type.shift();
-      } else {
-        const mixedOneOf: any[] = [];
-        schema.type.forEach(schemaType => {
-          mixedOneOf.push({
-            ...schema,
-            type: schemaType,
-          });
-        });
-
-        schema = {
-          oneOf: mixedOneOf,
-        };
-      }
-    }
-
     ['anyOf', 'oneOf'].forEach((polyType: 'anyOf' | 'oneOf') => {
       if (polyType in schema && Array.isArray(schema[polyType])) {
         schema[polyType].forEach((item, idx) => {
@@ -454,6 +428,117 @@ export default function toJSONSchema(
     }
   }
 
+  if ('type' in schema) {
+    // `nullable` isn't a thing in JSON Schema but it was in OpenAPI 3.0 so we should retain and
+    // translate it into something that's compatible with JSON Schema.
+    if ('nullable' in schema) {
+      if (Array.isArray(schema.type)) {
+        schema.type.push('null');
+      } else if (schema.type !== null && schema.type !== 'null') {
+        schema.type = [schema.type, 'null'];
+      }
+
+      delete schema.nullable;
+    }
+
+    if (schema.type === null) {
+      // `type: null` is possible in JSON Schema but we're translating it to a string version
+      // so we don't need to worry about asserting nullish types in our implementations of this
+      // generated schema.
+      schema.type = 'null';
+    } else if (Array.isArray(schema.type)) {
+      if (schema.type.includes(null)) {
+        schema.type[schema.type.indexOf(null)] = 'null';
+      }
+
+      schema.type = Array.from(new Set(schema.type));
+
+      // We don't need `type: [<type>]` when we can just as easily make it `type: <type>`.
+      if (schema.type.length === 1) {
+        schema.type = schema.type.shift();
+      } else if (schema.type.includes('array') || schema.type.includes('object')) {
+        // If we have a `null` type but there's only two types present then we can remove `null`
+        // as an option and flag the whole schema as `nullable`.
+        const isNullable = schema.type.includes('null');
+
+        if (schema.type.length === 2 && isNullable) {
+          // If this is `array | null` or `object | null` then we don't need to do anything.
+        } else {
+          // If this mixed type has non-primitives then we for convenience of our implementation
+          // we're moving them into a `oneOf`.
+          const nonPrimitives: any[] = [];
+
+          // Because we're moving an `array` and/or an `object` into a `oneOf` we also want to take
+          // with it its specific properties that maybe present on our current schema.
+          Object.entries({
+            // json-schema.org/understanding-json-schema/reference/array.html
+            array: [
+              'additionalItems',
+              'contains',
+              'items',
+              'maxContains',
+              'maxItems',
+              'minContains',
+              'minItems',
+              'prefixItems',
+              'uniqueItems',
+            ],
+
+            // https://json-schema.org/understanding-json-schema/reference/object.html
+            object: [
+              'additionalProperties',
+              'maxProperties',
+              'minProperties',
+              'nullable',
+              'patternProperties',
+              'properties',
+              'propertyNames',
+              'required',
+            ],
+          }).forEach(([typeKey, keywords]) => {
+            if (!schema.type.includes(typeKey as JSONSchema7TypeName)) {
+              return;
+            }
+
+            const reducedSchema: any = removeUndefinedObjects({
+              type: isNullable ? [typeKey, 'null'] : typeKey,
+
+              allowEmptyValue: (schema as any).allowEmptyValue ?? undefined,
+              deprecated: schema.deprecated ?? undefined,
+              description: schema.description ?? undefined,
+              readOnly: schema.readOnly ?? undefined,
+              title: schema.title ?? undefined,
+              writeOnly: schema.writeOnly ?? undefined,
+            });
+
+            keywords.forEach((t: keyof SchemaObject) => {
+              if (t in schema) {
+                reducedSchema[t] = schema[t];
+                delete schema[t];
+              }
+            });
+
+            nonPrimitives.push(reducedSchema);
+          });
+
+          schema.type = schema.type.filter(t => t !== 'array' && t !== 'object');
+          if (schema.type.length === 1) {
+            schema.type = schema.type.shift();
+          }
+
+          // Because we may have encountered a fully mixed non-primitive type like `array | object`
+          // we only want to retain the existing schema object if we still have types remaining
+          // in it.
+          if (schema.type.length > 1) {
+            schema = { oneOf: [schema, ...nonPrimitives] };
+          } else {
+            schema = { oneOf: nonPrimitives };
+          }
+        }
+      }
+    }
+  }
+
   if (RMOAS.isSchema(schema, isPolymorphicAllOfChild)) {
     // JSON Schema doesn't support OpenAPI-style examples so we need to reshape them a bit.
     if ('example' in schema) {
@@ -516,7 +601,7 @@ export default function toJSONSchema(
     // If we didn't have any immediately defined examples, let's search backwards and see if we can
     // find one. But as we're only looking for primitive example, only try to search for one if
     // we're dealing with a primitive schema.
-    if (schema.type !== 'array' && schema.type !== 'object' && !schema.examples) {
+    if (!hasSchemaType(schema, 'array') && !hasSchemaType(schema, 'object') && !schema.examples) {
       const foundExample = searchForExampleByPointer(currentLocation, prevSchemas);
       if (foundExample) {
         // We can only really deal with primitives, so only promote those as the found example if
@@ -527,7 +612,7 @@ export default function toJSONSchema(
       }
     }
 
-    if (schema.type === 'array') {
+    if (hasSchemaType(schema, 'array')) {
       if ('items' in schema) {
         if (!Array.isArray(schema.items) && Object.keys(schema.items).length === 1 && RMOAS.isRef(schema.items)) {
           // `items` contains a `$ref`, so since it's circular we should do a no-op here and log
@@ -549,15 +634,13 @@ export default function toJSONSchema(
         // array. Since throwing a complete failure isn't ideal, we can see that they meant for the
         // type to be `object`, so we can do our best to shape the data into what they were
         // intending it to be.
-        // README-6R
         schema.type = 'object';
       } else {
         // This is a fix to handle cases where we have a malformed array with no `items` property
         // present.
-        // README-8E
-        schema.items = {};
+        (schema as any).items = {};
       }
-    } else if (schema.type === 'object') {
+    } else if (hasSchemaType(schema, 'object')) {
       if ('properties' in schema) {
         Object.keys(schema.properties).forEach(prop => {
           if (

package/src/samples/index.ts

@@ -110,7 +110,7 @@ function sampleFromSchema(
     }
   }
 
-  if (type === 'object') {
+  if (type === 'object' || (Array.isArray(type) && type.includes('object'))) {
     const props = objectify(properties);
     const obj: Record<string, any> = {};
     // eslint-disable-next-line no-restricted-syntax
@@ -145,7 +145,7 @@ function sampleFromSchema(
     return obj;
   }
 
-  if (type === 'array') {
+  if (type === 'array' || (Array.isArray(type) && type.includes('array'))) {
     // `items` should always be present on arrays, but if it isn't we should at least do our best
     // to support its absence.
     if (typeof items === 'undefined') {