feat: when linking to another schema in docs, use ref, close #26

src/document/docs.ts

@@ -4,7 +4,7 @@ import stringify from 'json-stable-stringify'
 import json2md from 'json2md'
 import la from 'lazy-ass'
 import quote from 'quote'
-import { flatten, toLower } from 'ramda'
+import { flatten } from 'ramda'
 import {
   getExample,
   getObjectSchema,
@@ -15,7 +15,7 @@ import {
 import { CustomFormats } from '../formats'
 import { ObjectSchema, SchemaCollection } from '../objects'
 import { documentCustomFormats } from './doc-formats'
-import { documentSchema } from './utils'
+import { anchor, documentSchema } from './utils'
 
 const ticks = quote({ quotes: '`' })
 const title = [{ h1: 'Schemas' }]
@@ -78,8 +78,6 @@ export function documentSchemas(
 
   const fragments = flatten(schemaNames(schemas).map(toDoc))
 
-  const anchor = (s: string) => toLower(s.replace(/[\.@]/g, ''))
-
   const schemaNameToTopLevelLink = (schemaName: string) =>
     `[${schemaName}](#${anchor(schemaName)})`
 

src/document/utils.ts

@@ -1,11 +1,12 @@
 import quote from 'quote'
 import { find, toLower } from 'ramda'
-import { normalizeName, schemaNames } from '..'
+import { normalizeName, schemaNames, semverToString } from '..'
 import { CustomFormats } from '../formats'
 import {
   JsonProperties,
   JsonProperty,
   JsonSchema,
+  ObjectSchema,
   SchemaCollection,
 } from '../objects'
 
@@ -28,6 +29,16 @@ const knownSchemaNames = (schemas: SchemaCollection) => schemaNames(schemas)
 const isSchemaName = (schemas: SchemaCollection) => (s: string) =>
   knownSchemaNames(schemas).includes(normalizeName(s))
 
+// removes all characters to have a link
+export const anchor = (s: string) => toLower(s.replace(/[\.@]/g, ''))
+
+export const anchorForSchema = (s: ObjectSchema): string => {
+  const schemaName = toLower(normalizeName(s.schema.title))
+  const seeVersion = semverToString(s.version)
+  const nameAndVersion = `${schemaName}@${seeVersion}`
+  return anchor(nameAndVersion)
+}
+
 export const enumToMarkdown = enumeration => {
   if (!enumeration) {
     return emptyMark
@@ -38,18 +49,31 @@ export const enumToMarkdown = enumeration => {
 export const formatToMarkdown = (
   schemas?: SchemaCollection,
   formats?: CustomFormats,
-) => (value: JsonProperty) => {
+) => (value: JsonProperty): string => {
   if (!value.format) {
     if (value.see) {
-      return schemas && isSchemaName(schemas)(value.see)
-        ? `[${value.see}](#${toLower(normalizeName(value.see))})`
-        : ticks(value.see)
+      if (typeof value.see === 'string') {
+        // try finding schema by name
+        return schemas && isSchemaName(schemas)(value.see)
+          ? `[${value.see}](#${toLower(normalizeName(value.see))})`
+          : ticks(value.see)
+      } else {
+        const seeSchema: ObjectSchema = value.see
+        const schemaName = `${seeSchema.schema.title}`
+        const seeVersion = semverToString(seeSchema.version)
+        const nameAndVersion = `${schemaName}@${seeVersion}`
+        const seeAnchor = anchorForSchema(seeSchema)
+        return schemas && isSchemaName(schemas)(schemaName)
+          ? `[${nameAndVersion}](#${seeAnchor})`
+          : ticks(nameAndVersion)
+      }
     } else {
       return emptyMark
     }
   }
 
   if (formats && isCustomFormat(formats)(value.format)) {
+    // point at the formats section
     return `[${value.format}](#formats)`
   }
 

src/objects.ts

@@ -45,7 +45,7 @@ export type JsonProperty = {
   required?: boolean | string[]
   properties?: JsonProperties
   items?: JsonProperty
-  see?: string
+  see?: string | ObjectSchema
   title?: string
   patternProperties?: object
   additionalProperties?: boolean

test/document-format-test.ts

@@ -1,7 +1,11 @@
 import test from 'ava'
 import { JsonProperty } from '../src'
-import { emptyMark, formatToMarkdown } from '../src/document/utils'
-import { exampleFormats, schemas } from './example-schemas'
+import {
+  anchorForSchema,
+  emptyMark,
+  formatToMarkdown,
+} from '../src/document/utils'
+import { exampleFormats, person100, schemas } from './example-schemas'
 
 test('no format', t => {
   const value: JsonProperty = {
@@ -38,6 +42,29 @@ test('custom format', t => {
   t.is(result, '[name](#formats)', 'points at the custom formats section')
 })
 
-test.only('schema pointing at another schema', t => {
+test('schema using "see" text', t => {
+  t.plan(1)
+  const value: JsonProperty = {
+    type: 'object',
+    see: 'another thing',
+  }
+  const result = formatToMarkdown(undefined, exampleFormats)(value)
+  t.is(result, '`another thing`', 'adds quotes')
+})
+
+test('anchorForSchema', t => {
+  t.is(anchorForSchema(person100), 'person100')
+})
+
+test('schema pointing at another schema', t => {
   t.true('person' in schemas, 'there is a schema named "person"')
+  const value: JsonProperty = {
+    type: 'array',
+    items: {
+      ...person100.schema,
+    },
+    see: person100,
+  }
+  const result = formatToMarkdown(schemas, exampleFormats)(value)
+  t.is(result, '[Person@1.0.0](#person100)')
 })

test/example-schemas.ts

@@ -19,7 +19,7 @@ export const exampleFormats: CustomFormats = {
 }
 
 // individual schema describing "Person" v1.0.0
-const person100: ObjectSchema = {
+export const person100: ObjectSchema = {
   version: {
     major: 1,
     minor: 0,
@@ -67,7 +67,7 @@ const team100: ObjectSchema = {
         items: {
           ...person100.schema,
         },
-        see: person100.schema.title,
+        see: person100,
       },
     },
   },

test/snapshots/document-test.ts.md

@@ -166,7 +166,7 @@ Generated by [AVA](https://ava.li).
     ␊
     name | type | format␊
     --- | --- | ---␊
-    `people` | array | [Person](#person)␊
+    `people` | array | [Person@1.0.0](#person100)␊
     ␊
     ␊
     Example:␊
@@ -230,7 +230,7 @@ Generated by [AVA](https://ava.li).
     ␊
     name | type | format␊
     --- | --- | ---␊
-    `people` | array | [Person](#person)␊
+    `people` | array | [Person@1.0.0](#person100)␊
     ␊
     ␊
     Example:␊