Repository navigation
Add a core/media-query ability (read-only Media Library coverage) #1062
Description
Activity
I would love to take this on!
The proposal makes complete sense. I will start scaffolding
core/read-mediawiring the input arguments directly into the existing REST media controller logic to ensure the permission model (upload_filesfor listing,read_postfor attachments) remains identical.@sarthaknagoshe2002 you'll likely want to verify approach with @jorgefilipecosta first to ensure what's planned aligns with his decided approach for abilities broadly-speaking
Hi @jeffpaul and @jorgefilipecosta,
Thanks for the ping! I have the implementation and test suite ready locally. To make sure it aligns with Jorge's approach across the core abilities suite (mirroring the patterns established in
core/read-content#739 andcore/read-users), here is a summary of the approach taken:1. Shape & Schema
- Name & Category:
core/read-mediaregistered in thecontentcategory (gated under the Custom Abilities experiment withwp_abilities_api_initpriority11to cleanly override core copies). - Dual Mode (
oneOf):- Single Item Mode (
id): Returns the media object directly. - Collection Query Mode (
search,mime_type,parent,author,per_page,page,orderby,order): Returns{ items, total, total_pages }.
- Single Item Mode (
- Validation: Strict
additionalProperties: falseon each branch with branch-local defaults omitted from schema (handled via runtime fallbacks) for clean client-side validator compilation.
2. Permissions (Parity with REST
wp/v2/media)- Query Mode: Coarse check requiring the
upload_filescapability (subscribers and contributors cannot list the media library). - Single Item & Row-level:
- Attached items: Checks
read_poston the parent post (attachments of private posts are hidden unless the caller has read access to the parent). - Unattached or Orphaned items: Requires both
upload_filesandread_poston the attachment (hides unattached private media from non-owner authors).
- Attached items: Checks
3. Output & Efficiency
- Output fields:
id,title,alt_text,caption,description,mime_type,file_size,dimensions(width,height),source_url,available_sizes,parent,author,date,date_gmt,modified,modified_gmt, andmeta. - Safe strings: Returns raw strings for
captionanddescriptionto preventthe_content/wpautop/autoembedfilters from injecting HTML wrappers (like<p class="attachment">). available_sizes: Structured array of image sub-sizes (thumbnail,medium,full, etc.) for images; empty array for non-image attachments.- Meta: Restricts
metastrictly to registered post meta withshow_in_rest => true. - Annotations:
readonly: true,idempotent: true,destructive: false,open_world: false.
4. Tests & Quality
- Integration Tests: PHPUnit test suite covering role-based permissions (Admin, Author, Contributor, Subscriber, Anonymous, non-owner Author), orphaned parents, unattached private media, exact pagination, registered
show_in_restmeta, and core override behavior. - E2E Tests: Playwright spec testing client-side
executeAbility( 'core/read-media', ... )from@wordpress/abilitiesin the browser.
@jorgefilipecosta, please let me know if this approach sounds good or if there are any specific adjustments you'd like made. If everything looks good, I can push the branch and open the PR right away!
- Name & Category:
- changed the title
[-]Add a core/read-media ability (read-only Media Library coverage)[/-][+]Add a `core/media-query` ability (read-only Media Library coverage)[/+]on Oct 1, 2026 I’ve updated the title and description to reflect yesterday’s Core AI chat and the direction @jorgefilipecosta shared in the draft proposal. We’re aligning the names of read-only abilities that query collections around
core/$collection-query, so this ability becomescore/media-query.Reacted by Sarthak Nagoshe- added a parent issue
on Oct 7, 2026
Split out from #40, as requested there on 2026-07-16, so the media abilities can be planned and tracked on their own.
What problem does this address?
The WordPress 7.2 roadmap commits the AI team to "expand read-only coverage to resources such as media, taxonomies, and comments." Today the
core/read-*set covers settings, content (posts and pages), and users; nothing lets an agent or an MCP client discover what is in the Media Library, so the most common editorial asks ("find the hero image we used for the spring campaign", "which attachments have no alt text") cannot be answered through abilities.Proposal
Add a single read ability following the read/manage pattern from the merge proposal and the shape
core/read-contentalready established:core/media-querycontentid(single attachment) or list arguments:search,mime_type(family or exact),parent(attached post),author,date_query(deferred, as for content),per_page,page,orderby,order. Returnstotalandtotal_pagesalongsideitemsso callers can page.metalimited to registered,show_in_restmeta. No file contents.wp/v2/mediaread checks:upload_filesfor listing, per-itemread_poston the attachment, unattached items visible only to users who canupload_files. Private parents hide their attachments unless the caller can read the parent.readonly: true,idempotent: true,destructive: false.public => falseby default like the other core reads;show_in_restopt-in.Out of scope here: uploading, editing, or deleting attachments (
core/manage-media, tracked separately), and image generation.Why this shape
find-media-items+get-media-itemkeeps the tool count down for agents, the argument WordPress Core Abilities #40 settled on for settings.Acceptance
show_in_restmeta only.docs/abilities.md(or wherever the core reads are documented).Path to core
Prototype here per the 7.1 deferral decision; open the Trac ticket once the shape has settled, alongside
core/content-query(#64606) andcore/users-query(#64657).