feat(JSON Schema): Allow for inline $refs

package.json

@@ -41,6 +41,7 @@
     "@stencila/dev-config": "1.4.10",
     "@stencila/encoda": "0.83.2",
     "@stencila/logga": "2.1.0",
+    "@stoplight/json-ref-resolver": "3.0.8",
     "@types/fs-extra": "8.0.1",
     "@types/jest": "24.9.1",
     "@types/js-yaml": "3.12.2",

ts/bindings/typescript.ts

@@ -176,7 +176,7 @@ const docComment = (description?: string, tags: string[] = []): string => {
 const schemaToType = (schema: Schema): string => {
   const { type, anyOf, allOf, $ref } = schema
 
-  if ($ref !== undefined) return `${$ref.replace('.schema.json', '')}`
+  if ($ref !== undefined) return $refToType($ref)
   if (anyOf !== undefined) return anyOfToType(anyOf)
   if (allOf !== undefined) return allOfToType(allOf)
   if (schema.enum !== undefined) return enumToType(schema.enum)
@@ -192,6 +192,15 @@ const schemaToType = (schema: Schema): string => {
   throw new Error(`Unhandled schema: ${JSON.stringify(schema)}`)
 }
 
+/**
+ * Convert a schema `$ref` (reference) to a Typescript type
+ *
+ * Assume that any `$ref`s refer to a type defined in the file.
+ */
+const $refToType = ($ref: string): string => {
+  return $ref.replace('.schema.json', '')
+}
+
 /**
  * Convert a schema with the `anyOf` property to a Typescript `Union` type.
  */

ts/helpers.ts

@@ -3,6 +3,7 @@
  * generating languages bindings and documentation.
  */
 
+import { Resolver } from '@stoplight/json-ref-resolver'
 import fs from 'fs-extra'
 import globby from 'globby'
 import path from 'path'
@@ -11,7 +12,8 @@ import Schema from './schema-interface'
 export { default as Schema } from './schema-interface'
 
 /**
- * Read the schemas from `public/*.schema.json`.
+ * Read the schemas from `public/*.schema.json` and dereference
+ * any inline references.
  */
 export async function readSchemas(
   glob: string | string[] = path.join(
@@ -21,10 +23,13 @@ export async function readSchemas(
     '*.schema.json'
   )
 ): Promise<Schema[]> {
-  // Read in the schemas
   const files = await globby(glob)
   return Promise.all(
-    files.map(async (file: string): Promise<Schema> => fs.readJSON(file))
+    files.map(async (file: string) => {
+      const resolver = new Resolver()
+      const resolved = await resolver.resolve(await fs.readJSON(file))
+      return resolved.result
+    })
   )
 }
 

ts/schema.ts

@@ -233,6 +233,7 @@ const checkSchema = (
       if (
         key === '$ref' &&
         typeof child === 'string' &&
+        !child.startsWith('#') &&
         !child.endsWith('Types') &&
         !schemas.has(child)
       ) {
@@ -383,13 +384,15 @@ const processSchema = (schemas: Map<string, Schema>, schema: Schema): void => {
       }
     }
 
-    // Replace any `$ref`s to YAML with a ref to the JSON generated in this function
+    // Replace any `$ref`s that are not internal (i.e. starting with `#`)
+    // with a ref to the JSON file generated by this function
     const walk = (node: Schema): void => {
       if (typeof node !== 'object') return
       for (const [key, child] of Object.entries(node)) {
         if (
           key === '$ref' &&
           typeof child === 'string' &&
+          !child.startsWith('#') &&
           !child.endsWith('.schema.json')
         )
           node[key] = child + '.schema.json'