Feature/wp schema alignment 2026 04 17

[gin0115]

This pull request introduces several major features and improvements to the WP REST Schema library, focusing on enhanced combinator support, improved handling of defaults and enums, and expanded documentation. The most important changes are the addition of root-level combinator types (One_Of_Type and Any_Of_Type), support for explicit null/falsy defaults, mixed-type enums, and the introduction of arg_options and required_properties. Several methods have also been deprecated for clarity.

Combinator Support and Object Schema Enhancements:

• Added abstract Combinator_Type base class and concrete Any_Of_Type for schema-root combinators, allowing schemas to express "one of" or "any of" relationships between variants. This enables advanced schema validation and clearer API contracts. (src/Argument/Combinator_Type.php [1] src/Argument/Any_Of_Type.php [2]
• Added required_properties() method to both Object_Type and Schema, allowing explicit marking of required object properties in the schema output, matching WordPress core conventions. (src/Argument/Object_Type.php, docs/Object-Type.md [1] docs/Schema.md [2]

Defaults and Enum Handling:

• Improved default value handling: default() now accepts null and all falsy values, and tracks explicit set-ness separately from the value, ensuring correct schema emission and introspection. (src/Argument/Argument.php [1] [2] [3]
• Enhanced expected() (enum) to accept any JSON-comparable value, including null, arrays, and objects, to match WP's internal validation semantics. (src/Argument/Argument.php [1] [2]

WP REST Integration and Extensibility:

• Introduced arg_options() method, enabling per-property pass-through of raw WP REST controller options (e.g., sanitize_callback, validate_callback) via the schema. (src/Argument/Argument.php src/Argument/Argument.phpR566-R589)

Deprecations and Documentation:

• Deprecated name() and all_of() methods, as they are either not part of WP REST schema or are no-ops under current WP behavior. (src/Argument/Argument.php [1] src/Argument/Attribute/Element_Requirements.php [2]
• Expanded and clarified documentation throughout, including combinator usage, default handling, enum values, and new/deprecated APIs. (README.md [1] [2] docs/Argument.md [3] [4] [5] [6] docs/Array-Type.md [7] docs/Object-Type.md [8] docs/Schema.md [9]

These changes make the schema builder more expressive, more closely aligned with WordPress core, and easier to use for complex API schemas.

[codecov]

Codecov Report

❌ Patch coverage is 98.79518% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 99.67%. Comparing base (d89a759) to head (1afd19f).
⚠️ Report is 34 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Parser/Array_Attribute_Parser.php	91.66%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master      #35      +/-   ##
============================================
+ Coverage     90.67%   99.67%   +9.00%     
- Complexity      260      265       +5     
============================================
  Files            16       19       +3     
  Lines           461      613     +152     
============================================
+ Hits            418      611     +193     
+ Misses           43        2      -41     

☔ 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.