adobe / adobe/jsonschema2md

Bug Report: Missing Warning for Unresolved References

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

Description

### Expected Behavior
When generating Markdown documentation from a JSON Schema, unresolved `$ref` references (e.g., pointing to non-existent schema properties) should trigger a warning in the console output.

### Actual Behavior
No warning is displayed when an unresolved `$ref` is encountered during Markdown generation. The process completes silently, potentially leading to incomplete or misleading documentation.

### Steps to Reproduce

1. Use the following JSON Schema:
```json
{
"meta:license": [
"Copyright 2017 Adobe Systems Incorporated. All rights reserved.",
"This file is licensed to you under the Apache License, Version 2.0 (the 'License');",
"you may not use this file except in compliance with the License. You may obtain a copy",
"of the License at http://www.apache.org/licenses/LICENSE-2.0"
],
"$schema": "http://json-schema.org/draft-06/schema#",
"$id": "https://example.com/schemas/complex",
"title": "Complex References",
"type": "object",
"description": "This is an example schema that uses types defined in other schemas.",
"properties": {
"refnamed": {
"version": "1.0.0",
"testProperty": "test"
},
"refrefed": {
"$ref": "#/properties/refnamed2",
"version": "1.0.0",
"testProperty": "test"
}
}
}
```

2. Run the following command:
```bash
jsonschema2md -d schemas/test -x -
```

3. Observe the console output:
```
loading 1 schemas
preparing schemas...
preparing schemas
preparing README...
building readme
README.md created
preparing documentation...
generating markdown
```

4. Note that no warning is shown for the broken reference:
```json
"$ref": "#/properties/refnamed2"
```

### Environment

- **Operating System**: Windows 11 (WSL2)
- **Node.js Version**: v22.17.0
- **jsonschema2md Version**: 8.0.3

### Additional Notes
- The issue may lead to silent failures in documentation generation, especially in large schemas where broken references are harder to detect manually.
- A warning or error message would greatly improve developer experience and reliability.

Contributor guide

Open the contributing guide

Research direction

Reproduce the issue with the supplied schema and run `jsonschema2md -d schemas/test -x -` to trace Markdown generation when `#/properties/refnamed2` cannot be resolved. Done means the console reports the unresolved `$ref` while generation continues or fails as specified, with coverage for this broken-reference case.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, json
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.