add shared schema across multiple root resolution

Author: Eomm

README.md

@@ -3,8 +3,13 @@
 [![CI](https://github.com/Eomm/json-schema-resolver/workflows/ci/badge.svg)](https://github.com/Eomm/json-schema-resolver/actions?query=workflow%3Aci)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](http://standardjs.com/)
 
-Resolve all `$refs` in your [JSON schema](https://json-schema.org/specification.html)!
+Resolve all `$refs` in your [JSON schema](https://json-schema.org/specification.html)!  
+This module will resolve the `$ref` keyword against the `externalSchemas` you will provide.
+If a reference is missing, it will not throw any error.
 
+The `$ref` will be modified to point to a local reference `#/definitions/<generated key>`.
+Moreover, the `definitions` keyword will be decorated with the external schemas to get only
+one JSON schema resolved as output.
 
 ## Install
 
@@ -14,7 +19,7 @@ npm install json-schema-resolver
 
 This plugin support Node.js >= 10
 
-## Usage
+## Usage: resolve one schema against external schemas
 
 ```js
 const RefResolver = require('json-schema-resolver')
@@ -83,6 +88,39 @@ const singleSchema = ref.resolve(inputSchema, { externalSchemas: [addresSchema]
 }
 ```
 
+## Usage: resolve multiple schemas against external shared schemas
+
+When you have multiple schemas to resolve against a collection of shared schema you need to use this
+module with little changes.
+
+This is needed to have all the same definitions path (`#/definitions/<generated key>`) across all the
+root schemas
+
+```js
+const ref = RefResolver({
+  clone: true, // Clone the input schema without changing it. Default: false
+  applicationUri: 'my-application.org', // You need to provide an unique URI to resolve relative `$id`s
+  externalSchemas: [addresSchema] // The schemas provided at the creation of the resolver, will be used evvery time `.resolve` will be called
+})
+
+const inputSchema = {
+  $id: 'http://example.com/SimplePerson',
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    address: { $ref: 'relativeAddress#' },
+    houses: { type: 'array', items: { $ref: 'relativeAddress#' } }
+  }
+}
+
+// the resolved schema DOES NOT have definitions added
+const singleSchema = ref.resolve(inputSchema)
+const anotherResolvedSchema = ref.resolve(input_2_Schema)
+
+// to get the definition you need only to call:
+const sharedDefinitions = ref.definitions()
+```
+
 ## License
 
 Licensed under [MIT](./LICENSE).

ref-resolver.js

@@ -33,11 +33,7 @@ const targetCfg = {
 // logic: https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.appendix.B.1
 function jsonSchemaResolver (options) {
   const ee = new EventEmitter()
-  const { clone, target } = Object.assign({}, defaultOpts, options)
-
-  if (!targetSupported.includes(target)) {
-    throw new Error(`Unsupported JSON schema version ${target}`)
-  }
+  const { clone, target, applicationUri, externalSchemas: rootExternalSchemas } = Object.assign({}, defaultOpts, options)
 
   const allIds = new Map()
   let rolling = 0
@@ -46,26 +42,47 @@ function jsonSchemaResolver (options) {
   const allRefs = []
   ee.on('$ref', collectRefs)
 
+  if (!targetSupported.includes(target)) {
+    throw new Error(`Unsupported JSON schema version ${target}`)
+  }
+
+  let defaultUri
+  if (applicationUri) {
+    defaultUri = getRootUri(applicationUri)
+
+    if (rootExternalSchemas) {
+      for (const es of rootExternalSchemas) { mapIds(ee, defaultUri, es) }
+      debug('Processed root external schemas')
+    }
+  } else if (rootExternalSchemas) {
+    throw new Error('If you set root externalSchema, the applicationUri option is needed')
+  }
+
   return {
-    resolve
+    resolve,
+    definitions () {
+      const defKey = targetCfg[target].def
+      const x = { [defKey]: {} }
+      allIds.forEach((json, baseUri) => {
+        x[defKey][json[kRefToDef]] = json
+      })
+      return x
+    }
   }
 
   function resolve (rootSchema, opts) {
     const { externalSchemas } = opts || {}
 
-    allIds.clear()
+    if (!rootExternalSchemas) {
+      allIds.clear()
+    }
     allRefs.length = 0
 
     if (clone) {
       rootSchema = cloner(rootSchema)
     }
 
-    // If present, the value for this keyword MUST be a string, and MUST
-    // represent a valid URI-reference [RFC3986].  This value SHOULD be
-    // normalized, and SHOULD NOT be an empty fragment <#> or an empty
-    // string <>.
-    const appUri = URI.parse(rootSchema.$id || 'application.uri')
-    appUri.fragment = undefined // remove fragment
+    const appUri = defaultUri || getRootUri(rootSchema.$id)
     debug('Found app URI %o', appUri)
 
     if (externalSchemas) {
@@ -96,16 +113,19 @@ function jsonSchemaResolver (options) {
       json.$ref = `#/definitions/${evaluatedJson[kRefToDef]}`
     })
 
-    const defKey = targetCfg[target].def
-    allIds.forEach((json, baseUri) => {
-      if (json[kConsumed] === true) {
-        if (!rootSchema[defKey]) {
-          rootSchema[defKey] = {}
+    if (externalSchemas) {
+      // only if user sets external schema add it to the definitions
+      const defKey = targetCfg[target].def
+      allIds.forEach((json, baseUri) => {
+        if (json[kConsumed] === true) {
+          if (!rootSchema[defKey]) {
+            rootSchema[defKey] = {}
+          }
+
+          rootSchema[defKey][json[kRefToDef]] = json
         }
-
-        rootSchema[defKey][json[kRefToDef]] = json
-      }
-    })
+      })
+    }
 
     return rootSchema
   }
@@ -193,4 +213,14 @@ function mapIds (ee, baseUri, json) {
   }
 }
 
+function getRootUri (strUri = 'application.uri') {
+  // If present, the value for this keyword MUST be a string, and MUST
+  // represent a valid URI-reference [RFC3986].  This value SHOULD be
+  // normalized, and SHOULD NOT be an empty fragment <#> or an empty
+  // string <>.
+  const uri = URI.parse(strUri)
+  uri.fragment = undefined
+  return uri
+}
+
 module.exports = jsonSchemaResolver

test/example.test.js

@@ -65,3 +65,74 @@ test('readme example', t => {
     }
   })
 })
+
+test('readme example #2', t => {
+  t.plan(2)
+
+  const addresSchema = {
+    $id: 'relativeAddress',
+    type: 'object',
+    properties: {
+      zip: { type: 'string' },
+      city: { type: 'string' }
+    }
+  }
+
+  const ref = RefResolver({
+    clone: true, // Clone the input schema without changing it. Default: false
+    applicationUri: 'my-application.org', // You need to provide an unique URI to resolve relative `$id`s
+    externalSchemas: [addresSchema] // The schemas provided at the creation of the resolver, will be used evvery time `.resolve` will be called
+  })
+
+  const inputSchema = {
+    $id: 'http://example.com/SimplePerson',
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      address: { $ref: 'relativeAddress#' },
+      houses: { type: 'array', items: { $ref: 'relativeAddress#' } }
+    }
+  }
+
+  const singleSchema = ref.resolve(inputSchema)
+  // the resolved schema DOES NOT have definitions added
+
+  // to get the definition you need only to call:
+  const sharedDefinitions = ref.definitions()
+
+  t.deepEqual(sharedDefinitions, {
+    definitions: {
+      'def-0': {
+        $id: 'relativeAddress',
+        type: 'object',
+        properties: {
+          zip: {
+            type: 'string'
+          },
+          city: {
+            type: 'string'
+          }
+        }
+      }
+    }
+  })
+
+  t.deepEqual(singleSchema, {
+    $id: 'my-application.org',
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string'
+      },
+      address: {
+        $ref: '#/definitions/def-0'
+      },
+      houses: {
+        type: 'array',
+        items: {
+          $ref: '#/definitions/def-0'
+        }
+      }
+    }
+  })
+})

test/ref-resolver.test.js

@@ -12,8 +12,9 @@ const save = (out) => require('fs').writeFileSync(`./out-${Date.now()}.json`, JS
 // https://json-schema.org/draft/2019-09/json-schema-core.html#idExamples
 
 test('wrong params', t => {
-  t.plan(1)
+  t.plan(2)
   t.throws(() => RefResolver({ target: 'draft-1000' }))
+  t.throws(() => RefResolver({ externalSchemas: [] }), 'need application uri')
 })
 
 test('$ref to root', t => {
@@ -159,7 +160,7 @@ test('dont resolve external schema missing', t => {
 
 test('dont resolve external schema missing #2', t => {
   t.plan(1)
-  const schema = factory('absoluteId-asoluteRef')
+  const schema = factory('absoluteId-absoluteRef')
 
   const resolver = RefResolver({ clone: true })
   const out = resolver.resolve(schema)

test/ref-root.test.js

@@ -0,0 +1,64 @@
+'use strict'
+
+const { test } = require('tap')
+const clone = require('rfdc')({ proto: true, circles: false })
+
+const RefResolver = require('../ref-resolver')
+const factory = require('./schema-factory')
+
+// eslint-disable-next-line
+const save = (out) => require('fs').writeFileSync(`./out-${Date.now()}.json`, JSON.stringify(out, null, 2))
+
+test('application uri priority', t => {
+  t.plan(3)
+
+  const schema = {
+    $id: 'http://example.com/SimplePerson',
+    type: 'object',
+    properties: { name: { type: 'string' } }
+  }
+
+  const opts = {
+    applicationUri: 'one-single-uri.to'
+  }
+
+  const resolver = RefResolver(opts)
+
+  resolver.resolve(schema)
+  t.notEqual(schema.$id, 'http://example.com/SimplePerson')
+  t.equal(schema.$id, 'one-single-uri.to')
+
+  const externalDef = resolver.definitions()
+  t.deepEqual(externalDef.definitions, {})
+})
+
+test('multiple resolve over same externals', t => {
+  t.plan(7)
+
+  const schema1 = factory('absoluteId-externalRef')
+  const originalSchema1 = clone(schema1)
+
+  const schema2 = factory('absoluteId-externalRef2')
+  const originalSchema2 = clone(schema2)
+
+  const opts = {
+    applicationUri: 'one-single-uri.to',
+    externalSchemas: [
+      factory('relativeId-noRef')
+    ]
+  }
+  const resolver = RefResolver(opts)
+
+  const out1 = resolver.resolve(schema1)
+  t.notMatch(schema1, originalSchema1, 'the refs has been changed')
+  t.deepEquals(out1, schema1)
+  t.notOk(schema1.definitions, 'definition has not been added')
+
+  const out2 = resolver.resolve(schema2)
+  t.notMatch(schema2, originalSchema2, 'the refs has been changed')
+  t.deepEquals(out2, schema2)
+  t.notOk(schema2.definitions, 'definition has not been added')
+
+  const externalDef = resolver.definitions()
+  t.deepEqual(externalDef.definitions['def-0'], factory('relativeId-noRef'))
+})

test/schemas/absoluteId-asoluteRef.js renamed to test/schemas/absoluteId-absoluteRef.js

@@ -0,0 +1,9 @@
+module.exports = {
+  $id: 'http://example.com/ComplexPerson',
+  type: 'object',
+  properties: {
+    surname: { type: 'string' },
+    garage: { $ref: 'relativeAddress#' },
+    votes: { type: 'integer', minimum: 1 }
+  }
+}