unresolved reference when using relative $ref

[wayneashleyberry]

What did you do

I tried generated markdown from a schema that makes use of relative definitions that are all in one file.

jsonschema2md -d ./schema.json

Splitting these references out into separate files with absolute URL's does work, but it makes the schema far less portable.

What did you expect to happen

Successfully generate markdown without any errors.

What happened

07
info: output directory: /Users/wayneberry/src/github.com/overhq/open-file-format-specification/out
schema /Users/wayneberry/src/github.com/overhq/open-file-format-specification/schema.json has no $id
info: finished reading /Users/wayneberry/src/github.com/overhq/open-file-format-specification/schema.json, beginning processing....
/Users/wayneberry/src/github.com/overhq/open-file-format-specification/schema.json
unresolved reference: #/definitions/Identifier
unresolved reference: #/definitions/Identifier
Output processed.
info: Processing complete.

What's your environment

• Operating System: macOS 10.14.1
• node.js version: v11.2.0

Do you have example files:

For this schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$ref": "#/definitions/Project",
    "definitions": {
        "Project": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
                "identifier": {
                    "$ref": "#/definitions/Identifier"
                }
            },
            "required": [
                "identifier",
                "layers",
                "size"
            ],
            "title": "Project"
        },
        "Identifier": {
            "type": "string",
            "minLength": 36,
            "maxLength": 36,
            "examples": [
                "1467103b-45d3-49fa-addc-374370f93e9c"
            ],
            "description": "A universally unique identifier as specified by https://www.ietf.org/rfc/rfc4122.txt"
        }
    }
}

I'm getting following Markdown

#  Schema

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Defined In |
|----------|------------|--------|--------------|-------------------|-----------------------|------------|
| Cannot be instantiated | Yes | Experimental | No | Forbidden | Permitted |  |

#  Definitions

| Property | Type | Group |
|----------|------|-------|
| [identifier](#identifier) | reference | `#/definitions/Project` |

## identifier


`identifier`

* is optional
* type: reference
* defined in this schema

### identifier Type


* []() – `#/definitions/Identifier`

[trieloff]

That's interesting. I have another workaround for you that does not force you to use absolute URLs in your refs (we are using the same thing for XDM):

"allOf": [
  {"$ref": "#/definitions/Project"}
]

[wayneashleyberry]

@trieloff good find, that is a decent workaround for the "unresolved reference" issue.

Perhaps a separate issue, but I'm finding the output for a schema with many definitions far inferior to multiple schema's with absolute references. Seeing a list of all properties with a "group" soon becomes unreadable when you have a few definitions in a single schema. The links to requirements also don't work. Would it be worth creating separate issues for these?

Alternatively, is it possible to use multiple absolute references in a single file?

Here's a quick screenshot of some rather unwieldy output:

[dskvr]

I agree with @wayneashleyberry, using separate schemas results in more verbose and usable output, that often more accurately describes the schemas. For example, I have a use case where we are consuming json-schemas in oas specifications after a conversion process (with json-schemas-to-open-api). The oas files are used for codegen, and so using relative references is an absolute must in order to generate code that has useful response and model class names. This makes definitions a non-starter for us.

For my use case, all self-authored remote references create a chicken-before-the-egg scenario for many modern schemas where in order to validate a deep schema, the entire schema repo is required to be published to web before resuming the build process, or some clever DNS resolver hacks. It's a pipeline nightmare.

For explicitly relative references, jsonschema2md could make some assumptions about the schema, such as that the relative references resolve (valid). Thus, can also assume both the name of the schema object (filename) and relative location of the generated .md file for all relative references.

While filename is may not be suitable for most applications, it's certainly better than the current state of affairs.

For example (in yaml because json is exhausting).

# a.json
type: object 
properties: 
  b:
    $ref: 'bar/b.yaml'

# ./foo/b.yaml
type: object
properties:
  c:
     $ref: 'foo/c.yaml' 

# ./foo/bar/c.yaml
type: string

a.md could assume the location of b.md is ./foo/b.md, and similarly, ./b.md could assume the location of c.md is ./bar/c.md. a.md is not aware of c.md (because it's not following the reference) and so relative path discovery or even saving paths in global scope during markdown generation is a non-issue.

This would require

• Creating directories for docs that mimmic the filesystem of the relative references (not applicable to my use case but seems like a valid requirement)
• Inferring title from filename and sanitizing (removing extension)

Synchronous, doesn't require refactoring of existing codebase.

For more perfect docs...

• Resolve the relative reference to attempt to infer name/title of schema (there are several maintained resolvers that support relative references)
• Fallback to filename if name/title is not found
• Walk schema for relative definition references within remote schemas.

Asynchronous, would likely require a bit of refactoring to codebase. Solves @wayneashleyberry 's issue entirely through the use of resolvers

I'm considering doing the first bit myself because it's low overhead and works for my particular implementation.

[trieloff]

@dskvr I'm happy to review all PRs you send my way, but I'm unlikely to implement it myself.

In any case, thank you for outlining the problem and approaches to solving it.

[rbuckland]

@dskvr have you started working on this issue ? I would like to help out (to resolve it :-). Let me know. Thanks

[teq0]

+1 for helping to fix this. I've just been refactoring our schemas as we have quite a few cases where there are shared components, and the output is now completely unusable, it's almost gibberish. We can't be the only ones using relative references.

[trieloff]

🎉 This issue has been resolved in version 4.2.2 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

[trieloff]

🎉 This issue has been resolved in version 5.0.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀