Page MenuHomePhabricator

Improve linting - enum descriptions
Closed, ResolvedPublic3 Estimated Story Points

Description

Improve linting to ensure enum values are explained in property descriptions.

Current situation

There's a single rule that checks whether values listed in the schema.enum field for a parameter are explained in the parameter description.

Conditions of acceptance

Add validation of descriptions according to the following conditions:

  • If parameters.[parameter].schema.items.enum exists, then parameters.[parameter].description contains an explanation of all values listed in that enum field.
  • If parameters.[parameter].content.[media object].schema.enum or parameters.[parameter].content.[media object].schema.items.enum exists, then parameters.[parameter].description contains an explanation of all values listed in that enum field.
  • If requestBody.content.[media type].schema.enum or requestBody.content.[media type].schema.items.enum exists, then requestBody.description contains an explanation of all values listed in that enum field.
  • If responses.[response].content.[media object].schema.enum or responses.[response].content.[media object].schema.items.enum exists, then responses.[response].description contains an explanation of all values listed in that enum field.

Also add checks that verify schema properties at any level of nesting/in the entire sub-tree in the schema, similarly to T424002:

  • If schema.[properties on any level].[property].enum or schema.[properties on any level].[property].items.enum exists, then description for that exact property ([property].description) contains an explanation of all values listed in that enum field.

All checks described in this task should return a message with severity info in case of failure.

Event Timeline

Atieno triaged this task as Medium priority.Apr 25 2026, 5:00 PM
Atieno moved this task from Incoming (Needs Triage) to To Refine on the MW-Interfaces-Team board.
KBach lowered the priority of this task from Medium to Low.Apr 27 2026, 3:17 PM
HCoplin-WMF set the point value for this task to 3.May 7 2026, 2:57 PM
HCoplin-WMF subscribed.

Notes from estimation:

  • We have similar rules that can be referenced, in terms of "if this, then that" rule enforcement.
  • Example definitions also follow a similar pattern of being able to define them in multiple places within the spec.

Resolving tasks as part of closing the sprint.