Skip to content

wp-env: Update JSON Schema with missing properties and add README docs#76115

Open
kraftbj wants to merge 4 commits intoWordPress:trunkfrom
kraftbj:env-client-json-schema
Open

wp-env: Update JSON Schema with missing properties and add README docs#76115
kraftbj wants to merge 4 commits intoWordPress:trunkfrom
kraftbj:env-client-json-schema

Conversation

@kraftbj
Copy link
Contributor

@kraftbj kraftbj commented Mar 4, 2026 •
edited
Loading

What?

Update the existing schemas/json/wp-env.json schema with missing properties and improve documentation for schema usage.

Why?

The existing wp-env JSON Schema was missing several configuration options that have been added to wp-env over time (autoPort, mysqlPort, lifecycle scripts afterReset/afterCleanup). It also lacked validation constraints (port ranges, phpVersion pattern, config/mappings value types). Meanwhile, the wp-env README and schemas README had no mention of the schema, making it hard to discover.

How?

  • Update schemas/json/wp-env.json with missing properties: autoPort (root-only), mysqlPort (shared), afterReset and afterCleanup lifecycle scripts.
  • Add validation constraints: port range (1-65535), phpVersion pattern (^[0-9]+\.[0-9]+$), config value types (string/number/boolean), mappings value types (string), phpmyadminPort null support.
  • Add $schema usage note to packages/env/README.md pointing to schemas.wp.org/trunk/wp-env.json.
  • Add wp-env.json to schemas/README.md description and usage examples.
  • Document schemas/json/ directory in AGENTS.md.

Testing Instructions

  1. Create or edit a .wp-env.json file in any project.
  2. Add "$schema": "https://schemas.wp.org/trunk/wp-env.json" (or use a relative path to schemas/json/wp-env.json).
  3. Verify your editor provides autocomplete for known keys (core, plugins, port, autoPort, mysqlPort, etc.).
  4. Verify unknown keys show a validation warning.
  5. Verify that root-only keys like autoPort and testsPort show warnings when placed inside an env override.

Testing Instructions for Keyboard

N/A — no UI changes.

@kraftbj
wp-env: Add JSON Schema for .wp-env.json configuration
0c80e5b 
Add a JSON Schema file that enables editor autocomplete and validation
for .wp-env.json configuration files. Users can opt in by adding a
$schema key pointing to the published schema URL.

The schema covers all root-level and per-environment options, including
the recently added autoPort option, and rejects unknown keys to catch
typos early.
@github-actions
Copy link

github-actions bot commented Mar 4, 2026 •
edited
Loading

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: kraftbj <kraftbj@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@ramonjd ramonjd added the [Type] Enhancement A suggestion for improvement. label Mar 4, 2026
ramonjd
ramonjd reviewed Mar 4, 2026
View reviewed changes
ramonjd
ramonjd reviewed Mar 4, 2026
View reviewed changes
packages/env/README.md
Comment on lines +589 to +597
To enable editor autocomplete and validation, add a `$schema` key:

```json
{
"$schema": "https://schemas.wordpress.org/wp-env.schema.json",
"plugins": [ "." ]
}
```

Copy link
Member

@ramonjd ramonjd Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a good to have regardless of whether we have a new schema doc or keep on using https://schemas.wp.org/trunk/wp-env.json 👍🏻

t-hamano
t-hamano reviewed Mar 5, 2026
View reviewed changes
Copy link
Contributor

@t-hamano t-hamano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kraftbj Thanks for the PR!

In fact, the schema and unit tests already exist, and I'd be happy to check them out.

@t-hamano t-hamano added [Type] Developer Documentation Documentation for developers [Tool] Env /packages/env and removed [Type] Enhancement A suggestion for improvement. labels Mar 5, 2026
kraftbj added 2 commits March 8, 2026 22:03
@kraftbj
wp-env: Update existing schema instead of adding a duplicate
02cf17b 
Remove the duplicate schema and test added in packages/env/lib/config/
and instead update the existing schemas/json/wp-env.json with the
missing properties: autoPort, mysqlPort, phpVersion pattern validation,
port range constraints, config/mappings typing, phpmyadminPort null
support, and afterReset/afterCleanup lifecycle scripts.

Also fix the $schema URL in the wp-env README to use schemas.wp.org
(consistent with other schemas), add wp-env.json to schemas/README.md,
and document the schemas directory in AGENTS.md.
@kraftbj
Merge remote-tracking branch 'origin/trunk' into env-client-json-schema
38fdeab
@kraftbj kraftbj changed the title wp-env: Add JSON Schema for .wp-env.json configuration wp-env: Update JSON Schema with missing properties and add README docs Mar 8, 2026
@kraftbj kraftbj requested review from ramonjd and t-hamano March 8, 2026 21:49
ramonjd
ramonjd reviewed Mar 8, 2026
View reviewed changes
Copy link
Member

@ramonjd ramonjd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for updating the schema with the new props 🙇🏻

Looking pretty good. Just had a couple of questions around validation.

schemas/json/wp-env.json Outdated
{
"type": "string"
"type": "string",
"pattern": "^[0-9]+\\.[0-9]+$"
Copy link
Member

@ramonjd ramonjd Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also wondering if this should match the runtime validator regex in checkVersion

This is a bit stricter, allowing x.x, but not x.x.x for example.

I'm looking at version_compare for examples.

What do you think?

Copy link
Contributor Author

@kraftbj kraftbj Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the thorough review! All three items addressed:

  • Added allowUnionTypes: true to the test AJV options
  • Updated port minimum to 0 to match the runtime checkPort validator — you're right it's a non-issue in practice but might as well match
  • Updated phpVersion pattern to ^[0-9]+(?:\.[0-9]+)*$ to match the runtime checkVersion regex, accepting "X", "X.X", and "X.X.X" formats

@kraftbj
wp-env: Address schema review feedback
a256c5c 
- Match runtime phpVersion validator pattern: accept "X", "X.X", and
  "X.X.X" formats instead of only "X.X"
- Match runtime port validator: allow port 0 (minimum: 0) to align with
  checkPort in validate-config.js
- Add allowUnionTypes to AJV options in schema test to support union
  type arrays in config additionalProperties
ramonjd
ramonjd approved these changes Mar 9, 2026
View reviewed changes
Copy link
Member

@ramonjd ramonjd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Thanks for the updates!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ramonjd ramonjd ramonjd approved these changes

@ObliviousHarmony ObliviousHarmony Awaiting requested review from ObliviousHarmony ObliviousHarmony is a code owner

@t-hamano t-hamano Awaiting requested review from t-hamano t-hamano is a code owner

Assignees

@kraftbj kraftbj

Labels

[Tool] Env /packages/env [Type] Developer Documentation Documentation for developers

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@kraftbj @ramonjd @t-hamano