[Feature]: Create Schema for JSON and YAML Config Files

[Kurt-von-Laven]

🚀 Feature Proposal

Write a draft v4 JSON schema defining Jest config files for inclusion in JSON SchemaStore.

Motivation

Jest config files are powerful, complex, and offer many options. A number of them (e.g., coverageReporters, coverageThreshold, moduleNameMapper, reporters, transform) have complex types, and a number (e.g., *PathIgnorePatterns) have long names.

Example

Offering a schema makes it easy for projects that desire to validate their config files to do so with minimal effort and receive precise, helpful, real-time in-editor warnings and autocomplete suggestions regarding typos in key names. A schema would also make it easy to validate Jest config files in CI. JSON Schema Store recommends use of draft v4 JSON schemas for maximum compatibility.

Pitch

"Quis custodiet ipsos custodes?" ("Who will guard the guards themselves?") ~ Satires (Satire IV lines 347-348), Decimus Junius Juvenalis (a.k.a., Juvenal)

Or as retold via Gru from Despicable Me:

I don't know whether or not a schema would catch any issues that Jest itself wouldn't catch when run, but it's generally preferable to catch issues as they are introduced, and auto-completion of keys is an appreciated productivity boost. A JSON schema is extremely precise documentation, leaving no ambiguity as to what constitutes a valid JSON/YAML config file. Using a JSON schema may simplify Jest's validation logic, facilitate automatically testing whether the JSON/YAML and JavaScript/TypeScript config file options are in sync with one another, and allow documentation to be auto-generated if these things aren't happening already. In the meantime, users who want stronger type checking and auto-completion can presently use a TypeScript file. However, dynamic code execution introduces another possible point of failure, and TypeScript config files require some extra setup (e.g., introducing a dev dependency on ts-node, which can be especially burdensome in high-security settings). Many projects also prefer to use static JSON or YAML config files for simplicity.

[SimenB]

Having a schema file would be awesome! 🙂 Very happy to accept a PR here for hosting one.

Ideally, we would write it using https://github.com/sinclairzx81/typebox or some such which also provides TS types and can generate the schema from code. That should ensure there's no drift (and we can then use ajv or something to validate).

Options supported are roughly https://github.com/facebook/jest/blob/ae1f04bf0a71482ffe9ddb0d93b28b8d2079e13d/packages/jest-types/src/Config.ts#L141-L264, so any schema should take those as a starting point

[kouraf]

Hi, i'd like to contribute to this 😄 if nobody is already working on it !
I also want to know where/when should we validate the JSON schema ? maybe inside jest-config🤔 ? and for the shcema should we create a new package like jest-json or something like that ? or just put it at the root as schema.json ?

[Kurt-von-Laven]

I don't believe anyone is working on it. We already use JSONSchemaStore via MegaLinter to validate all of our JSON and YAML configs that have schemas, but I imagine other users would appreciate Jest validating its own config file. I am not familiar enough with Jest internals to offer any helpful guidance to you unfortunately.

[Kurt-von-Laven]

Maybe @SimenB knows the answers to your questions?

[SimenB]

I'd start by using typebox (linked above) to build up the json schema in memory. We can then write that to disk for publishing somewhere (probably a new module, but we can look at that later), and use ajv or something to validate it internally within jest-config.

[SimenB]

For anyone looking to pick this up, I made a super rough (and probably non-working) start here: https://github.com/SimenB/jest/tree/schema

To write the schema to disk, run yarn build:js and then this script

// write-schema.mjs
import {writeFileSync} from 'fs';
import {InitialOptions} from '@jest/schemas';

writeFileSync('./schema.json', JSON.stringify(InitialOptions, null, 2));

Once we have a schema that works, we can start using it inside Jest. How to get that schema onto some schema store I don't know, but probably fairly straightforward

[SimenB]

I'll land that package in #12384, but it won't (nearly) cover the entire InitialOptions. PRs to expand it until it covers the entire thing would be appreciated 🙂 As mentioned there, once complete we'll write the JSON to disk (and validate it), but for now it should just extract the parts needed.

Branch now that some has landed: https://github.com/SimenB/jest/tree/schema-initial

[SimenB]

Published that in https://github.com/facebook/jest/releases/tag/v28.0.0-alpha.1

[Kurt-von-Laven]

Bravo! Adding schemas to JSON Schema Store is indeed straightforward and documented.

Once we have a schema that works, we can start using it inside Jest. How to get that schema onto some schema store I don't know, but probably fairly straightforward

[github-actions]

This issue is stale because it has been open for 1 year with no activity. Remove stale label or comment or this will be closed in 30 days.

[Kurt-von-Laven]

Not stale.