Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

New JSON generator schema

Đã đóng
#214 6 bình luận 3 reaction 2 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@avivkeller đang làm issue này rồi.

Từ ngày 15/9/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

Web Generator
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:

  1. Consumers know what to expect
  2. We can version the output files in a standardized way (via the $id property)
  3. 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:

Ngôn ngữ chính
JavaScript
Star
65
Fork
71
Merge trung bình
4 ngày 15 giờ
Pull request đã merge (30 ngày)
33

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của nodejs/doc-kit

Tất cả issue của nodejs/doc-kit

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.