unresolved reference when using relative $ref

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`

[rbuckland]

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

[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: