New JSON generator schema
@avivkeller ya está trabajando en esto.
Desde el 15/9/2026.
Evaluación
Este issue todavía no se ha evaluado.
Descripción
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)
- Lenguaje dominante
- JavaScript
- Estrellas
- 65
- Forks
- 71
- Merge medio
- 4 d 3 h
- PR fusionados (30 d)
- 31
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de nodejs/doc-kit
-
Dificultad 2/5 Medio día Aptitud para principiantes 68/100
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 64/100
-
Dificultad 3/5 1-2 días Aptitud para principiantes 65/100
-
Dificultad 3/5 1-2 días Aptitud para principiantes 45/100
Todos los issues de nodejs/doc-kit
Issues similares
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
-
area-deployment area-integrations triage:bot-seen
Dificultad 2/5 Medio día Aptitud para principiantes 86/100
-
Issue-Bug
Dificultad 2/5 1-3 horas Aptitud para principiantes 68/100
sugarlabs/musicblocks#8924 ·
-
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
ArduPilot/ardupilot_wiki#8088 ·
-
[BUG] createTool tools cannot be registered with Mastra when exactOptionalPropertyTypes is enabled Abiertocustomer-eng status: needs triage
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100