adobe / adobe/jsonschema2md

Stuck in "generating markdown" step - potential performance issue

Open
#251 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
JavaScript
Stars
724
Forks
150
Avg merge
18h 22m
Merged PRs (30d)
4

Description

## What did you do
I have 3 json schema files - `A.json`, `B.json`, `C.json`. A references B and B references C. However, when I run the `jsonschema2md` command, command gets stuck at the `gererating markdown` step.

```bash
$ jsonschema2md -d . -e json --out ../out
loading 3 schemas
writing schemas
writing schemas to ...
writing README
building readme
writing documentation
generating markdown // stuck here
```
In my research so far, it seems like this happens when there are too many incoming references to a definition and/or when an `array` based reference references another `array` based reference.

Please see the example below of all 3 files, I deliberately added few extra properties `extends[n]` to the `A.json` schema, which made the command got stuck. Please help.

## What did you expect to happen
Markdown to generate successfully.

## What happened
Command got stuck at `generating markdown` step

## What's your environment

* Operating System: macOs High Sierra `10.13.6`
* node.js version: `v14.3.0`

## Do you have example files:
`A.json`
```
{
"$id": "https://foo.bar/A",
"$schema": "http://json-schema.org/draft-07/schema#",

"type": "object",

"properties": {
"extends": {
"type": "array",
"items": {
"$ref": "https://foo.bar/B"
}
},
"extends2": {
"type": "array",
"items": {
"$ref": "https://foo.bar/B"
}
},
"extends3": {
"type": "array",
"items": {
"$ref": "https://foo.bar/B"
}
},
"extends4": {
"type": "array",
"items": {
"$ref": "https://foo.bar/B"
}
},
"extends5": {
"type": "array",
"items": {
"$ref": "https://foo.bar/B"
}
}
}
}
```
`B.json`
```
{
"$id": "https://foo.bar/B",
"$schema": "http://json-schema.org/draft-07/schema#",

"type": "array",
"items": {
"$ref": "https://foo.bar/C"
}
}
```

`C.json`
```
{
"$id": "https://foo.bar/C",
"$schema": "http://json-schema.org/draft-07/schema#",

"type": "string"
}
```

Contributor guide

Open the contributing guide

Research direction

Reproduce the hang with the jsonschema2md command and the provided A.json, B.json, and C.json files, focusing on the generating markdown step. Trace that entry point to determine why repeated array references prevent completion. Done means the example schemas generate Markdown successfully without remaining stuck.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
cli, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.