Skip to content

Enhance documentation for input and output schemas #141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
jonathanbossenger merged 1 commit into from
Nov 10, 2025
Merged

Enhance documentation for input and output schemas #141

jonathanbossenger merged 1 commit into from
Nov 10, 2025

Conversation

@jonathanbossenger
Copy link
Contributor

@jonathanbossenger jonathanbossenger commented Nov 10, 2025

Updated input_schema and output_schema descriptions to include JSON Schema links for better clarity.

@jonathanbossenger
Enhance documentation for input and output schemas
00c80c7 
Updated input_schema and output_schema descriptions to include JSON Schema links for better clarity.
@codecov
Copy link

codecov bot commented Nov 10, 2025 •
edited
Loading

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.39%. Comparing base (99e62d4) to head (00c80c7).
⚠️ Report is 1 commits behind head on trunk.

Additional details and impacted files 
@@            Coverage Diff            @@
##              trunk     #141   +/-   ##
=========================================
  Coverage     80.39%   80.39%           
  Complexity      178      178           
=========================================
  Files            20       20           
  Lines          1474     1474           
  Branches        120      119    -1     
=========================================
  Hits           1185     1185           
  Misses          289      289
Flag Coverage Δ
javascript 94.31% <ø> (ø)
unit 76.31% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@gziolo gziolo added the [Type] Developer Documentation Improvements or additions to documentation label Nov 10, 2025
@gziolo
Copy link
Member

gziolo commented Nov 10, 2025

Related PHPDoc comment:

abilities-api/includes/abilities-api.php

Lines 155 to 183 in 99e62d4

* ### Input and Output Schemas
*
* Schemas define the expected structure, type, and constraints for ability inputs
* and outputs using JSON Schema syntax. They serve two critical purposes: automatic
* validation of data passed to and returned from abilities, and self-documenting
* API contracts for developers.
*
* WordPress implements a validator based on a subset of the JSON Schema Version 4
* specification (https://json-schema.org/specification-links.html#draft-4).
* For details on supported JSON Schema properties and syntax, see the
* related WordPress REST API Schema documentation:
* https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/#json-schema-basics
*
* Defining schemas is mandatory when there is a value to pass or return.
* They ensure data integrity, improve developer experience, and enable
* better documentation:
*
* 'input_schema' => array(
* 'type' => 'string',
* 'description' => __( 'The text to be analyzed.', 'my-plugin' ),
* 'minLength' => 10,
* 'required' => true,
* ),
* 'output_schema' => array(
* 'type' => 'string',
* 'enum' => array( 'positive', 'negative', 'neutral' ),
* 'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ),
* 'required' => true,
* ),

@jonathanbossenger jonathanbossenger marked this pull request as ready for review November 10, 2025 13:59
@github-actions
Copy link

github-actions bot commented Nov 10, 2025

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: jonathanbossenger <[email protected]>
Co-authored-by: gziolo <[email protected]>

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

@jonathanbossenger jonathanbossenger enabled auto-merge (squash) November 10, 2025 13:59
@jonathanbossenger jonathanbossenger merged commit 272d306 into trunk Nov 10, 2025
40 checks passed
@jonathanbossenger jonathanbossenger deleted the docs/schema-link branch November 10, 2025 14:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gziolo gziolo gziolo approved these changes

Assignees

@jonathanbossenger jonathanbossenger

Labels

[Type] Developer Documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jonathanbossenger @gziolo