oas-normalize 7.1.0 → 8.0.0

package/README.md

@@ -1,26 +1,35 @@
-OpenAPI 3.x or Swagger 2.0? YAML or JSON? URL, path, string or object? Who cares! It just works.
+<p align="center">
+  <a href="https://npm.im/oas-normalize">
+    <img src="https://user-images.githubusercontent.com/33762/200434622-23946869-1965-46f8-8deb-f284b8d0b92c.png" alt="oas-normalize" />
+  </a>
+</p>
 
-This module uses a bunch of other great modules to do the heavy lifting, and normalizes everything!
+<p align="center">
+  Tooling for converting, valiating, and parsing OpenAPI, Swagger, and Postman API definitions
+</p>
 
-[![Build](https://github.com/readmeio/oas-normalize/workflows/CI/badge.svg)](https://github.com/readmeio/oas-normalize/) [![](https://img.shields.io/npm/v/oas-normalize)](https://npm.im/oas-normalize)
+<p align="center">
+  <a href="https://npm.im/oas-normalize"><img src="https://img.shields.io/npm/v/oas-normalize.svg?style=for-the-badge" alt="NPM Version"></a>
+  <a href="https://npm.im/oas-normalize"><img src="https://img.shields.io/node/v/oas-normalize.svg?style=for-the-badge" alt="Node Version"></a>
+  <a href="https://npm.im/oas-normalize"><img src="https://img.shields.io/npm/l/oas-normalize.svg?style=for-the-badge" alt="MIT License"></a>
+  <a href="https://github.com/readmeio/oas-normalize"><img src="https://img.shields.io/github/workflow/status/readmeio/oas-normalize/CI.svg?style=for-the-badge" alt="Build status"></a>
+</p>
 
-[![](https://d3vv6lp55qjaqc.cloudfront.net/items/1M3C3j0I0s0j3T362344/Untitled-2.png)](https://readme.com)
-
-# Install
+## Installation
 
 ```bash
-npm install oas-normalize --save
+npm install oas-normalize
 ```
 
-# Usage
+## Usage
 
 ```javascript
 import OASNormalize from 'oas-normalize';
 // const { default: OASNormalize } = require('oas-normalize'); // If you're using CJS.
 
 const oas = new OASNormalize(
-  // Or a string, pathname, JSON blob, whatever
   'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml'
+  // ...or a string, path, JSON blob, whatever you've got.
 );
 
 oas
@@ -34,7 +43,55 @@ oas
   });
 ```
 
-# Errors
+### `#bundle()`
+
+> **Note**
+>
+> Because Postman collections don't support `$ref` pointers, this method will automatically upconvert a Postman collection to OpenAPI if supplied one.
+
+Bundle up the given API definition, resolving any external `$ref` pointers in the process.
+
+```js
+await oas.bundle().then(definition => {
+  console.log(definition);
+});
+```
+
+### `#deref()`
+
+> **Note**
+>
+> Because Postman collections don't support `$ref` pointers, this method will automatically upconvert a Postman collection to OpenAPI if supplied one.
+
+Dereference the given API definition, resolving all `$ref` pointers in the process.
+
+```js
+await oas.deref().then(definition => {
+  console.log(definition);
+});
+```
+
+### `#validate({ convertToLatest?: boolean })`
+
+Validate and optionally convert to OpenAPI, a given API definition. This supports Swagger 2.0, OpenAPI 3.x API definitions as well as Postman 2.x collections.
+
+Please note that if you've supplied a Postman collection to the library it will **always** be converted to OpenAPI, using [postman-to-openapi](https://github.com/joolfe/postman-to-openapi), and we will only validate resulting OpenAPI definition.
+
+```js
+await oas.validate().then(definition => {
+  console.log(definition);
+});
+```
+
+#### Options
+
+<!-- prettier-ignore-start -->
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `convertToLatest` | Boolean | By default `#validate` will not upconvert Swagger API definitions to OpenAPI so if you wish for this to happen, supply `true`. |
+<!-- prettier-ignore-end -->
+
+#### Error Handling
 
 For validation errors, when available, you'll get back an object:
 
@@ -55,35 +112,9 @@ For validation errors, when available, you'll get back an object:
 
 `message` is almost always there, but `path` is less dependable.
 
-# Helper Functions
-
-> **Note:** All of these functions are promise-driven.
-
-If you want some more functionality, you can do anything here:
-
-<!--
-Prettier's table formatting sucks, hence the ignore block below.
--->
-<!-- prettier-ignore-start -->
-| Function | What it does |
-| :--- | :--- |
-| `.load()` | Just load the file, valid or not, as JSON |
-| `.bundle()` | Bring together all files into one JSON blob (but retain `$ref` pointers) |
-| `.deref()` | Resolve `$ref` pointers |
-| `.validate([convertToLatest?])` | Validate the whole thing! |
-<!-- prettier-ignore-end -->
-
-# Other Little Features
-
-### Always Return OpenAPI 3.x
-
-If you want `.validate()` to always return an OpenAPI 3.x definition, supply `true` as its argument:
-
-```js
-OASNormalize.validate(true).then(...);
-```
+### Options
 
-### Enable Local Paths
+##### Enable local paths
 
 For security reasons, you need to opt into allowing fetching by a local path. To enable it supply the `enablePaths` option to the class instance:
 
@@ -91,7 +122,7 @@ For security reasons, you need to opt into allowing fetching by a local path. To
 const oas = new OASNormalize('./petstore.json', { enablePaths: true });
 ```
 
-### Colorized errors
+##### Colorized errors
 
 If you wish errors from `.validate()` to be styled and colorized, supply `colorizeErrors: true` to your instance of `OASNormalize`:
 

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 import type { OpenAPI } from 'openapi-types';
+import * as utils from './lib/utils';
 export declare type Options = {
     colorizeErrors?: boolean;
     enablePaths?: boolean;
 };
+export declare const isAPIDefinition: typeof utils.isAPIDefinition;
+export declare const getAPIDefinitionType: typeof utils.getAPIDefinitionType;
 export default class OASNormalize {
     cache: {
         bundle?: false | OpenAPI.Document;
@@ -13,10 +16,12 @@ export default class OASNormalize {
     opts: Options;
     type: boolean | string;
     constructor(file: any, opts?: Options);
+    /**
+     * @private
+     */
     load(): Promise<any>;
     /**
-     * Bundle up the given OpenAPI or Swagger definition, resolving any external `$ref` pointers in
-     * the process.
+     * Bundle up the given API definition, resolving any external `$ref` pointers in the process.
      *
      */
     bundle(): Promise<import("openapi-types").OpenAPIV2.Document<{}> | import("openapi-types").OpenAPIV3.Document<{}> | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
@@ -57,7 +62,7 @@ export default class OASNormalize {
         components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
     }>, "components">)>;
     /**
-     * Dereference the given OpenAPI or Swagger.
+     * Dereference the given API definition.
      *
      */
     deref(): Promise<import("openapi-types").OpenAPIV2.Document<{}> | import("openapi-types").OpenAPIV3.Document<{}> | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
@@ -98,14 +103,10 @@ export default class OASNormalize {
         components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
     }>, "components">)>;
     /**
-     * Validate a given OpenAPI or Swagger definition, potentially upconverting it from Swagger to
-     * OpenAPI in the process if you wish.
-     *
-     */
-    validate(convertToLatest?: boolean): Promise<any>;
-    /**
-     * Retrieve the OpenAPI or Swagger version of the current API definition.
+     * Validate, and potentially convert to OpenAPI, a given API definition.
      *
      */
-    version(): Promise<string>;
+    validate(opts?: {
+        convertToLatest?: boolean;
+    }): Promise<any>;
 }

package/dist/index.js

@@ -73,11 +73,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
+exports.getAPIDefinitionType = exports.isAPIDefinition = void 0;
 var fs_1 = __importDefault(require("fs"));
 var openapi_parser_1 = __importDefault(require("@readme/openapi-parser"));
 var node_fetch_1 = __importDefault(require("node-fetch"));
+var postman_to_openapi_1 = __importDefault(require("postman-to-openapi"));
 var swagger2openapi_1 = __importDefault(require("swagger2openapi"));
 var utils = __importStar(require("./lib/utils"));
+exports.isAPIDefinition = utils.isAPIDefinition;
+exports.getAPIDefinitionType = utils.getAPIDefinitionType;
 var OASNormalize = /** @class */ (function () {
     function OASNormalize(file, opts) {
         this.file = file;
@@ -89,7 +93,9 @@ var OASNormalize = /** @class */ (function () {
             deref: false
         };
     }
-    // Internal API for the most part
+    /**
+     * @private
+     */
     OASNormalize.prototype.load = function () {
         return __awaiter(this, void 0, void 0, function () {
             var resolve, _a, resp, contents;
@@ -133,8 +139,7 @@ var OASNormalize = /** @class */ (function () {
         });
     };
     /**
-     * Bundle up the given OpenAPI or Swagger definition, resolving any external `$ref` pointers in
-     * the process.
+     * Bundle up the given API definition, resolving any external `$ref` pointers in the process.
      *
      */
     OASNormalize.prototype.bundle = function () {
@@ -144,6 +149,15 @@ var OASNormalize = /** @class */ (function () {
                 if (this.cache.bundle)
                     return [2 /*return*/, Promise.resolve(this.cache.bundle)];
                 return [2 /*return*/, this.load()
+                        .then(function (schema) {
+                        // Though Postman collections don't support `$ref` pointers for us to bundle we'll still
+                        // upconvert it to an OpenAPI definition file so our returned dataset is always one of
+                        // those for a Postman dataset.
+                        if (utils.isPostman(schema)) {
+                            return (0, postman_to_openapi_1["default"])(JSON.stringify(schema), null, { outputFormat: 'json' }).then(JSON.parse);
+                        }
+                        return schema;
+                    })
                         .then(function (schema) { return openapi_parser_1["default"].bundle(schema); })
                         .then(function (bundle) {
                         _this.cache.bundle = bundle;
@@ -153,7 +167,7 @@ var OASNormalize = /** @class */ (function () {
         });
     };
     /**
-     * Dereference the given OpenAPI or Swagger.
+     * Dereference the given API definition.
      *
      */
     OASNormalize.prototype.deref = function () {
@@ -163,6 +177,15 @@ var OASNormalize = /** @class */ (function () {
                 if (this.cache.deref)
                     return [2 /*return*/, Promise.resolve(this.cache.deref)];
                 return [2 /*return*/, this.load()
+                        .then(function (schema) {
+                        // Though Postman collections don't support `$ref` pointers for us to dereference we'll
+                        // still upconvert it to an OpenAPI definition file so our returned dataset is always one
+                        // of those for a Postman dataset.
+                        if (utils.isPostman(schema)) {
+                            return (0, postman_to_openapi_1["default"])(JSON.stringify(schema), null, { outputFormat: 'json' }).then(JSON.parse);
+                        }
+                        return schema;
+                    })
                         .then(function (schema) { return openapi_parser_1["default"].dereference(schema); })
                         .then(function (dereferenced) {
                         _this.cache.deref = dereferenced;
@@ -172,54 +195,58 @@ var OASNormalize = /** @class */ (function () {
         });
     };
     /**
-     * Validate a given OpenAPI or Swagger definition, potentially upconverting it from Swagger to
-     * OpenAPI in the process if you wish.
+     * Validate, and potentially convert to OpenAPI, a given API definition.
      *
      */
-    OASNormalize.prototype.validate = function (convertToLatest) {
-        if (convertToLatest === void 0) { convertToLatest = false; }
+    OASNormalize.prototype.validate = function (opts) {
+        if (opts === void 0) { opts = { convertToLatest: false }; }
         return __awaiter(this, void 0, void 0, function () {
-            var colorizeErrors;
+            var convertToLatest, colorizeErrors;
             var _this = this;
             return __generator(this, function (_a) {
+                convertToLatest = opts.convertToLatest;
                 colorizeErrors = this.opts.colorizeErrors;
-                return [2 /*return*/, this.load().then(function (schema) { return __awaiter(_this, void 0, void 0, function () {
+                return [2 /*return*/, this.load()
+                        .then(function (schema) { return __awaiter(_this, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            if (!utils.isPostman(schema)) {
+                                return [2 /*return*/, schema];
+                            }
+                            return [2 /*return*/, (0, postman_to_openapi_1["default"])(JSON.stringify(schema), null, { outputFormat: 'json' }).then(JSON.parse)];
+                        });
+                    }); })
+                        .then(function (schema) { return __awaiter(_this, void 0, void 0, function () {
                         var baseVersion, clonedSchema;
                         return __generator(this, function (_a) {
-                            baseVersion = parseInt(utils.version(schema), 10);
-                            if (baseVersion === 1) {
-                                return [2 /*return*/, Promise.reject(new Error('Swagger v1.2 is unsupported.'))];
+                            if (!utils.isSwagger(schema) && !utils.isOpenAPI(schema)) {
+                                return [2 /*return*/, Promise.reject(new Error('The supplied API definition is unsupported.'))];
                             }
-                            else if (baseVersion === 2 || baseVersion === 3) {
-                                clonedSchema = JSON.parse(JSON.stringify(schema));
-                                return [2 /*return*/, openapi_parser_1["default"]
-                                        .validate(clonedSchema, {
-                                        validate: {
-                                            colorizeErrors: colorizeErrors
-                                        }
-                                    })
-                                        .then(function () {
-                                        if (!convertToLatest) {
-                                            return schema;
-                                        }
-                                        return swagger2openapi_1["default"].convertObj(schema, { anchors: true }).then(function (options) {
-                                            return options.openapi;
-                                        });
-                                    })["catch"](function (err) { return Promise.reject(err); })];
+                            else if (utils.isSwagger(schema)) {
+                                baseVersion = parseInt(schema.swagger, 10);
+                                if (baseVersion === 1) {
+                                    return [2 /*return*/, Promise.reject(new Error('Swagger v1.2 is unsupported.'))];
+                                }
                             }
-                            return [2 /*return*/, Promise.reject(new Error('The supplied API definition is unsupported.'))];
+                            clonedSchema = JSON.parse(JSON.stringify(schema));
+                            return [2 /*return*/, openapi_parser_1["default"]
+                                    .validate(clonedSchema, {
+                                    validate: {
+                                        colorizeErrors: colorizeErrors
+                                    }
+                                })
+                                    .then(function () {
+                                    if (!convertToLatest) {
+                                        return schema;
+                                    }
+                                    return swagger2openapi_1["default"]
+                                        .convertObj(schema, { anchors: true })
+                                        .then(function (options) { return options.openapi; });
+                                })["catch"](function (err) { return Promise.reject(err); })];
                         });
                     }); })];
             });
         });
     };
-    /**
-     * Retrieve the OpenAPI or Swagger version of the current API definition.
-     *
-     */
-    OASNormalize.prototype.version = function () {
-        return this.load().then(function (schema) { return utils.version(schema); });
-    };
     return OASNormalize;
 }());
 exports["default"] = OASNormalize;

package/dist/lib/utils.d.ts

@@ -1,21 +1,47 @@
-import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 /**
- * Retrieve the Swagger or OpenAPI version that a given Swagger or OpenAPI definition are targeting.
+ * Determine if a given variable is a `Buffer`.
  *
  */
-export declare function version(schema: OpenAPIV2.Document & OpenAPIV3.Document & OpenAPIV3_1.Document): string;
+export declare function isBuffer(obj: any): any;
 /**
- * Determine if a given variable is a `Buffer`.
+ * Determine the type of a given variable. Returns `false` if unrecognized.
  *
  */
-export declare function isBuffer(obj: any): any;
+export declare function getType(obj: any): false | "path" | "json" | "buffer" | "string-json" | "string-yaml" | "url";
+/**
+ * Determine if a given schema if an OpenAPI definition.
+ *
+ */
+export declare function isOpenAPI(schema: Record<string, unknown>): boolean;
+/**
+ * Determine if a given schema is a Postman collection.
+ *
+ * Unfortunately the Postman schema spec doesn't have anything like `openapi` or `swagger` for us
+ * to look at but it does require that `info` and `item` be present and as `item` doesn't exist in
+ * OpenAPI or Swagger we can use the combination of those two properties to determine if what we
+ * have is a Postman collection.
+ *
+ * @see {@link https://schema.postman.com/json/collection/v2.0.0/collection.json}
+ * @see {@link https://schema.postman.com/json/collection/v2.1.0/collection.json}
+ */
+export declare function isPostman(schema: Record<string, unknown>): boolean;
+/**
+ * Determine if a given schema if an Swagger definition.
+ *
+ */
+export declare function isSwagger(schema: Record<string, unknown>): boolean;
 /**
  * Convert a YAML blob or stringified JSON object into a JSON object.
  *
  */
 export declare function stringToJSON(string: string | Record<string, unknown>): any;
 /**
- * Determine the type of a given variable. Returns `false` if unrecognized.
+ * Determine if a given schema is an API definition that we can support.
  *
  */
-export declare function getType(obj: any): false | "path" | "json" | "buffer" | "string-json" | "string-yaml" | "url";
+export declare function isAPIDefinition(schema: Record<string, unknown>): boolean;
+/**
+ * Retrieve the type of API definition that a given schema is.
+ *
+ */
+export declare function getAPIDefinitionType(schema: Record<string, unknown>): "unknown" | "openapi" | "postman" | "swagger";

package/dist/lib/utils.js

@@ -3,16 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
-exports.getType = exports.stringToJSON = exports.isBuffer = exports.version = void 0;
+exports.getAPIDefinitionType = exports.isAPIDefinition = exports.stringToJSON = exports.isSwagger = exports.isPostman = exports.isOpenAPI = exports.getType = exports.isBuffer = void 0;
 var js_yaml_1 = __importDefault(require("js-yaml"));
-/**
- * Retrieve the Swagger or OpenAPI version that a given Swagger or OpenAPI definition are targeting.
- *
- */
-function version(schema) {
-    return schema.swagger || schema.openapi;
-}
-exports.version = version;
 /**
  * Determine if a given variable is a `Buffer`.
  *
@@ -24,20 +16,6 @@ function isBuffer(obj) {
         obj.constructor.isBuffer(obj));
 }
 exports.isBuffer = isBuffer;
-/**
- * Convert a YAML blob or stringified JSON object into a JSON object.
- *
- */
-function stringToJSON(string) {
-    if (typeof string === 'object') {
-        return string;
-    }
-    else if (string.match(/^\s*{/)) {
-        return JSON.parse(string);
-    }
-    return js_yaml_1["default"].load(string);
-}
-exports.stringToJSON = stringToJSON;
 /**
  * Determine the type of a given variable. Returns `false` if unrecognized.
  *
@@ -65,3 +43,73 @@ function getType(obj) {
     return false;
 }
 exports.getType = getType;
+/**
+ * Determine if a given schema if an OpenAPI definition.
+ *
+ */
+function isOpenAPI(schema) {
+    return !!schema.openapi;
+}
+exports.isOpenAPI = isOpenAPI;
+/**
+ * Determine if a given schema is a Postman collection.
+ *
+ * Unfortunately the Postman schema spec doesn't have anything like `openapi` or `swagger` for us
+ * to look at but it does require that `info` and `item` be present and as `item` doesn't exist in
+ * OpenAPI or Swagger we can use the combination of those two properties to determine if what we
+ * have is a Postman collection.
+ *
+ * @see {@link https://schema.postman.com/json/collection/v2.0.0/collection.json}
+ * @see {@link https://schema.postman.com/json/collection/v2.1.0/collection.json}
+ */
+function isPostman(schema) {
+    return !!schema.info && !!schema.item;
+}
+exports.isPostman = isPostman;
+/**
+ * Determine if a given schema if an Swagger definition.
+ *
+ */
+function isSwagger(schema) {
+    return !!schema.swagger;
+}
+exports.isSwagger = isSwagger;
+/**
+ * Convert a YAML blob or stringified JSON object into a JSON object.
+ *
+ */
+function stringToJSON(string) {
+    if (typeof string === 'object') {
+        return string;
+    }
+    else if (string.match(/^\s*{/)) {
+        return JSON.parse(string);
+    }
+    return js_yaml_1["default"].load(string);
+}
+exports.stringToJSON = stringToJSON;
+/**
+ * Determine if a given schema is an API definition that we can support.
+ *
+ */
+function isAPIDefinition(schema) {
+    return isOpenAPI(schema) || isPostman(schema) || isSwagger(schema);
+}
+exports.isAPIDefinition = isAPIDefinition;
+/**
+ * Retrieve the type of API definition that a given schema is.
+ *
+ */
+function getAPIDefinitionType(schema) {
+    if (isOpenAPI(schema)) {
+        return 'openapi';
+    }
+    else if (isPostman(schema)) {
+        return 'postman';
+    }
+    else if (isSwagger(schema)) {
+        return 'swagger';
+    }
+    return 'unknown';
+}
+exports.getAPIDefinitionType = getAPIDefinitionType;

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "oas-normalize",
-  "version": "7.1.0",
-  "description": "OpenAPI 3.x or Swagger 2.0? YAML or JSON? URL, path, string or object? Who cares! It just works.",
+  "version": "8.0.0",
+  "description": "Tooling for converting, valiating, and parsing OpenAPI, Swagger, and Postman API definitions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "engines": {
     "node": ">=14"
   },
-  "tags": [
+  "keywords": [
     "api",
+    "apidoc",
     "apis",
+    "documentation",
+    "microservice",
+    "postman",
+    "oai",
+    "oas",
     "openapi",
-    "swagger",
+    "openapi document",
     "openapi initiative",
-    "openapi specification",
     "openapi spec",
-    "openapi document",
-    "oai",
-    "oas",
-    "apidoc",
-    "microservice",
-    "documentation"
+    "openapi specification",
+    "swagger"
   ],
   "repository": {
     "type": "git",
@@ -45,17 +46,17 @@
     "js-yaml": "^4.1.0",
     "node-fetch": "^2.6.1",
     "openapi-types": "^12.0.0",
+    "postman-to-openapi": "^2.7.1",
     "swagger2openapi": "^7.0.8"
   },
   "devDependencies": {
-    "@readme/eslint-config": "^10.0.0",
-    "@readme/oas-examples": "^5.1.1",
+    "@readme/eslint-config": "^10.1.3",
+    "@readme/oas-examples": "^5.8.1",
     "@types/jest": "^28.1.6",
     "@types/js-yaml": "^4.0.5",
     "@types/node-fetch": "^2.6.2",
     "eslint": "^8.21.0",
     "jest": "^28.0.3",
-    "jet": "^0.8.1",
     "nock": "^13.2.4",
     "prettier": "^2.7.1",
     "ts-jest": "^28.0.7",

package/src/index.ts

@@ -4,6 +4,7 @@ import fs from 'fs';
 
 import openapiParser from '@readme/openapi-parser';
 import fetch from 'node-fetch';
+import postmanToOpenAPI from 'postman-to-openapi';
 
 import converter from 'swagger2openapi';
 
@@ -14,6 +15,9 @@ export type Options = {
   enablePaths?: boolean;
 };
 
+export const isAPIDefinition = utils.isAPIDefinition;
+export const getAPIDefinitionType = utils.getAPIDefinitionType;
+
 export default class OASNormalize {
   cache: {
     bundle?: false | OpenAPI.Document;
@@ -44,7 +48,9 @@ export default class OASNormalize {
     };
   }
 
-  // Internal API for the most part
+  /**
+   * @private
+   */
   async load() {
     if (this.cache.load) return Promise.resolve(this.cache.load);
 
@@ -82,14 +88,23 @@ export default class OASNormalize {
   }
 
   /**
-   * Bundle up the given OpenAPI or Swagger definition, resolving any external `$ref` pointers in
-   * the process.
+   * Bundle up the given API definition, resolving any external `$ref` pointers in the process.
    *
    */
   async bundle() {
     if (this.cache.bundle) return Promise.resolve(this.cache.bundle);
 
     return this.load()
+      .then(schema => {
+        // Though Postman collections don't support `$ref` pointers for us to bundle we'll still
+        // upconvert it to an OpenAPI definition file so our returned dataset is always one of
+        // those for a Postman dataset.
+        if (utils.isPostman(schema)) {
+          return postmanToOpenAPI(JSON.stringify(schema), null, { outputFormat: 'json' }).then(JSON.parse);
+        }
+
+        return schema;
+      })
       .then(schema => openapiParser.bundle(schema))
       .then(bundle => {
         this.cache.bundle = bundle;
@@ -98,13 +113,23 @@ export default class OASNormalize {
   }
 
   /**
-   * Dereference the given OpenAPI or Swagger.
+   * Dereference the given API definition.
    *
    */
   async deref() {
     if (this.cache.deref) return Promise.resolve(this.cache.deref);
 
     return this.load()
+      .then(schema => {
+        // Though Postman collections don't support `$ref` pointers for us to dereference we'll
+        // still upconvert it to an OpenAPI definition file so our returned dataset is always one
+        // of those for a Postman dataset.
+        if (utils.isPostman(schema)) {
+          return postmanToOpenAPI(JSON.stringify(schema), null, { outputFormat: 'json' }).then(JSON.parse);
+        }
+
+        return schema;
+      })
       .then(schema => openapiParser.dereference(schema))
       .then(dereferenced => {
         this.cache.deref = dereferenced;
@@ -113,19 +138,31 @@ export default class OASNormalize {
   }
 
   /**
-   * Validate a given OpenAPI or Swagger definition, potentially upconverting it from Swagger to
-   * OpenAPI in the process if you wish.
+   * Validate, and potentially convert to OpenAPI, a given API definition.
    *
    */
-  async validate(convertToLatest = false) {
+  async validate(opts: { convertToLatest?: boolean } = { convertToLatest: false }) {
+    const convertToLatest = opts.convertToLatest;
     const colorizeErrors = this.opts.colorizeErrors;
 
-    return this.load().then(async schema => {
-      const baseVersion = parseInt(utils.version(schema), 10);
+    return this.load()
+      .then(async schema => {
+        if (!utils.isPostman(schema)) {
+          return schema;
+        }
+
+        return postmanToOpenAPI(JSON.stringify(schema), null, { outputFormat: 'json' }).then(JSON.parse);
+      })
+      .then(async schema => {
+        if (!utils.isSwagger(schema) && !utils.isOpenAPI(schema)) {
+          return Promise.reject(new Error('The supplied API definition is unsupported.'));
+        } else if (utils.isSwagger(schema)) {
+          const baseVersion = parseInt(schema.swagger, 10);
+          if (baseVersion === 1) {
+            return Promise.reject(new Error('Swagger v1.2 is unsupported.'));
+          }
+        }
 
-      if (baseVersion === 1) {
-        return Promise.reject(new Error('Swagger v1.2 is unsupported.'));
-      } else if (baseVersion === 2 || baseVersion === 3) {
         /**
          * `openapiParser.validate()` dereferences schemas at the same time as validation and does
          * not give us an option to disable this. Since all we already have a dereferencing method
@@ -146,22 +183,11 @@ export default class OASNormalize {
               return schema;
             }
 
-            return converter.convertObj(schema, { anchors: true }).then((options: { openapi: OpenAPI.Document }) => {
-              return options.openapi;
-            });
+            return converter
+              .convertObj(schema, { anchors: true })
+              .then((options: { openapi: OpenAPI.Document }) => options.openapi);
           })
           .catch(err => Promise.reject(err));
-      }
-
-      return Promise.reject(new Error('The supplied API definition is unsupported.'));
-    });
-  }
-
-  /**
-   * Retrieve the OpenAPI or Swagger version of the current API definition.
-   *
-   */
-  version() {
-    return this.load().then(schema => utils.version(schema));
+      });
   }
 }

package/src/lib/utils.ts

@@ -1,15 +1,5 @@
-import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
-
 import YAML from 'js-yaml';
 
-/**
- * Retrieve the Swagger or OpenAPI version that a given Swagger or OpenAPI definition are targeting.
- *
- */
-export function version(schema: OpenAPIV2.Document & OpenAPIV3.Document & OpenAPIV3_1.Document) {
-  return schema.swagger || schema.openapi;
-}
-
 /**
  * Determine if a given variable is a `Buffer`.
  *
@@ -23,20 +13,6 @@ export function isBuffer(obj: any) {
   );
 }
 
-/**
- * Convert a YAML blob or stringified JSON object into a JSON object.
- *
- */
-export function stringToJSON(string: string | Record<string, unknown>) {
-  if (typeof string === 'object') {
-    return string;
-  } else if (string.match(/^\s*{/)) {
-    return JSON.parse(string);
-  }
-
-  return YAML.load(string);
-}
-
 /**
  * Determine the type of a given variable. Returns `false` if unrecognized.
  *
@@ -61,3 +37,72 @@ export function getType(obj: any) {
 
   return false;
 }
+
+/**
+ * Determine if a given schema if an OpenAPI definition.
+ *
+ */
+export function isOpenAPI(schema: Record<string, unknown>) {
+  return !!schema.openapi;
+}
+
+/**
+ * Determine if a given schema is a Postman collection.
+ *
+ * Unfortunately the Postman schema spec doesn't have anything like `openapi` or `swagger` for us
+ * to look at but it does require that `info` and `item` be present and as `item` doesn't exist in
+ * OpenAPI or Swagger we can use the combination of those two properties to determine if what we
+ * have is a Postman collection.
+ *
+ * @see {@link https://schema.postman.com/json/collection/v2.0.0/collection.json}
+ * @see {@link https://schema.postman.com/json/collection/v2.1.0/collection.json}
+ */
+export function isPostman(schema: Record<string, unknown>): boolean {
+  return !!schema.info && !!schema.item;
+}
+
+/**
+ * Determine if a given schema if an Swagger definition.
+ *
+ */
+export function isSwagger(schema: Record<string, unknown>) {
+  return !!schema.swagger;
+}
+
+/**
+ * Convert a YAML blob or stringified JSON object into a JSON object.
+ *
+ */
+export function stringToJSON(string: string | Record<string, unknown>) {
+  if (typeof string === 'object') {
+    return string;
+  } else if (string.match(/^\s*{/)) {
+    return JSON.parse(string);
+  }
+
+  return YAML.load(string);
+}
+
+/**
+ * Determine if a given schema is an API definition that we can support.
+ *
+ */
+export function isAPIDefinition(schema: Record<string, unknown>) {
+  return isOpenAPI(schema) || isPostman(schema) || isSwagger(schema);
+}
+
+/**
+ * Retrieve the type of API definition that a given schema is.
+ *
+ */
+export function getAPIDefinitionType(schema: Record<string, unknown>) {
+  if (isOpenAPI(schema)) {
+    return 'openapi';
+  } else if (isPostman(schema)) {
+    return 'postman';
+  } else if (isSwagger(schema)) {
+    return 'swagger';
+  }
+
+  return 'unknown';
+}