Add linting rules for operations and paths
Closed, ResolvedPublic3 Estimated Story Points
Actions

Assigned To

Authored By

	KBach
	Apr 7 2026, 2:25 PM

Project Tags

Referenced Files

None

Subscribers

Description

Operations are the core functionality of any API and their correct documentation is critical to empowering API users. This set of rules completes the functionality for verification of the operation object in the linter.

Conditions of acceptance

Validate that the operation has a description (severity: error) - example
Validate that the operation has an operationId (severity: error) - example
- Validate that the value in the operationId field is unique among all operationId fields present in the description (severity: error)
Validate that if the OAD has a top-level tags object, the operation has a tags field (severity: warn) - example #1, example #2
Validate that the operation has an externalDocs field (severity: hint) - example
Validate that the path has a summary (severity: hint) - example
Validate that the path has a description (severity: hint)

Extra resources

OpenAPI Specification v3.0.0

Related Objects
Search...

Status	Assigned	Task
Open	KBach	T422476 [Hypothesis] 5.2.5b: Productionalize API spec linting
Resolved	KBach	T422479 [5.2.5b Epic] Implement and improve linter rules
Resolved	KineticPelagic	T422504 Add linting rules for operations and paths

Event Timeline

KBach created this task.Apr 7 2026, 2:25 PM

KBach updated the task description. (Show Details)Apr 7 2026, 2:49 PM

BPirkle triaged this task as Medium priority.Apr 7 2026, 10:11 PM

BPirkle moved this task from Incoming (Needs Triage) to Backlog on the MW-Interfaces-Team board.

Flagging that I believe we already completed much of the parameter work: https://phabricator.wikimedia.org/T410397

I noticed this morning that the spreadsheet wasn't updated, but that part should be done! :)

KBach renamed this task from Add linting rules for operations and parameters to Add linting rules for operations and paths.Apr 8 2026, 9:22 AM

KBach updated the task description. (Show Details)

I updated the task title and description - adding path and removing parameter validation. Validation of parameter examples (currently crossed out in the description) is awaiting review in this merge request.

HCoplin-WMF moved this task from Backlog to To Refine on the MW-Interfaces-Team board.Apr 8 2026, 1:22 PM

Validation of parameter examples is now merged and removed from the scope of this task.

KBach updated the task description. (Show Details)Apr 9 2026, 11:14 AM

aaron added a project: Tool-wmf-openapi-linter.Apr 9 2026, 3:09 PM

HCoplin-WMF added a project: MediaWiki-REST-API.Apr 9 2026, 3:11 PM

HCoplin-WMF set the point value for this task to 3.

HCoplin-WMF moved this task from To Refine to Ready, Sized, & Prioritized on the MW-Interfaces-Team board.Apr 9 2026, 3:19 PM

KBach updated the task description. (Show Details)Apr 20 2026, 12:17 PM

HCoplin-WMF moved this task from Ready, Sized, & Prioritized to MWI-Sprint-32 (2026-04-21 to 2026-05-05) on the MW-Interfaces-Team board.Apr 21 2026, 12:57 PM

HCoplin-WMF edited projects, added: MW-Interfaces-Team (MWI-Sprint-32 (2026-04-21 to 2026-05-05)); removed: MW-Interfaces-Team.

KBach assigned this task to KineticPelagic.Apr 23 2026, 2:41 PM

Depends on https://phabricator.wikimedia.org/T415914.

In T422504#11797157, @HCoplin-WMF wrote:

Flagging that I believe we already completed much of the parameter work: https://phabricator.wikimedia.org/T410397

I noticed this morning that the spreadsheet wasn't updated, but that part should be done! :)

@HCoplin-WMF , what is the spreadsheet you mean here?

This spreadsheet! :D https://docs.google.com/spreadsheets/d/1nxGsWvpu_GXD28Fw19A8WWJa5cumWNke2E9m-22Qxu4/edit?gid=0#gid=0

It is/was our original tracker for figuring out rules and which rules were implemented. Apologies for missing the link originally!

kineticpelagic opened https://gitlab.wikimedia.org/toolforge-repos/wmf-openapi-linter/-/merge_requests/17

Draft: Add rules for operations and paths (T422504)

KineticPelagic moved this task from Committed to In Progress on the MW-Interfaces-Team (MWI-Sprint-32 (2026-04-21 to 2026-05-05)) board.Apr 28 2026, 7:51 PM

KineticPelagic moved this task from In Progress to Code Review on the MW-Interfaces-Team (MWI-Sprint-32 (2026-04-21 to 2026-05-05)) board.Apr 28 2026, 8:00 PM

Of the comments I posted in my draft Merge Request, I realized that this one may be relevant for you to opine on, @KBach . This thought is a supplementary one beyond the above requirements.

Edit:
Never mind - I was being silly. The subset test I asked about exists here already. 🎊

aaron changed the task status from Open to In Progress.Apr 29 2026, 3:28 PM

@KBach , @AGhirelli-WMF perceptively made this comment in reviewing my code. In response, I softened this language in my most recent commit, to better align with the task description of severity: "warn". May you confirm if "Validate that if the OAD has a top-level tags object, the operation has a tags field" deserves severity: "warn" or severity: "error"?