New JSON generator schema
维护者通常 3 天内回复
@avivkeller 已经在做这个了。
开始于 2026年9月15日。
评估
这个 Issue 还没有评估数据。
描述
Enter your suggestions in details:
Background
This issue is regarding the new format for the JSON generator.
It only pertains to the format of the JSON files, the implementation details will be discussed once a censensus is reached here.
Why a new format?
There are a handful of issues with the current format, with some of the main ones being:
- Maintainability
- Without a pre-defined schema, it can be harder to tell where a property should be expected to go within the output
- There isn't a great way to communicate changes to this schema when they happen
- Consumability
- Users don't know what to expect without going through the generator's code or looking through all of the outputted JSON files
- The current format represents some fields in unfortunate ways (i.e. Markdown being parsed in HTML for descriptions)
Relevant: DefinitelyTyped/DefinitelyTyped#70298, nodejs/api-docs-tooling#57
The new format
The newly proposed schema for json generator is available here.
An example of it being used for Buffer is available here.
The new proposed schema for the json-all generator is available here.
An example of it being used is available here.
Key Points
JSON Schema
The new formats have JSON schemas defined. This gives us three main advantages over the current format:
- Consumers know what to expect
- We can version the output files in a standardized way (via the
$idproperty) - The schemas can be used to generate the types used within the JSON generator. This will help with maintaining the generator in the long run since we don't have to worry about them getting out of sync.
JSDoc Property Names
JSDoc keys (i.e. @name, @type) are used in the format.
This is mainly to make the files easier to consume.
TODOs
Here's what's left to be done with the new format:
- How do we want to represent sections that are just text (aka not defining any API)? Should these just be combined into their parent's
descriptionproperty? (Good examples for reference: the entirety of addons, Buffers and character encodings)
- 主要语言
- JavaScript
- 星标
- 67
- 派生
- 74
- 平均合并
- 4 天 22 小时
- 30 天内合并 PR
- 39
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
nodejs/doc-kit 的其他 Issue
-
难度 2/5 半天 新手友好度 68/100
维护者通常 3 天内回复
-
难度 2/5 1-3 小时 新手友好度 64/100
维护者通常 3 天内回复
-
难度 5/5 一周以上 新手友好度 35/100
维护者通常 3 天内回复
-
Can the links to previews in the comments generated by a PR include `doc-kit`?可能已有人在做 @avivkeller 于 18 天前认领。 未关闭
nodejs/doc-kit#1098 · 2 条评论 · 已指派 1 人 ·
维护者通常 3 天内回复
-
难度 3/5 1-2 天 新手友好度 45/100
维护者通常 3 天内回复
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 68/100
CircuitVerse/CircuitVerse#7967 · 1 条评论 · 1 个 reaction ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
CopilotKit/aimock#491 ·
维护者通常 1 天内回复
-
cvss-severity:high devguard l3montree-cybersecurity/.../devguard-documentation pkg:devguard/l3montree-c.../devguard-documentation risk:low state:open
难度 2/5 1-3 小时 新手友好度 68/100
l3montree-dev/devguard-documentation#338 · 1 条评论 ·
-
bug runtime spec compliance
难度 2/5 1-3 小时 新手友好度 75/100
frostney/GocciaScript#1413 ·
维护者通常 1 天内回复
-
bug
难度 2/5 1-3 小时 新手友好度 75/100
keyxmakerx/Chronicle#967 ·
维护者通常 1 天内回复