Bug Report: Missing Warning for Unresolved References
- 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
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