The current version of schema property example validation is too permissive and only reports issues when examples for all schema properties are missing. Assuming examples aren't present in any other locations as described in T423411, the linter should report an issue when at least one property example is missing in the schema.
To fix, change the validation mechanism to be more restrictive (i.e. raise an issue when at least one schema property example is missing) for the following rules:
- wikimedia-paths-parameter-example-exists
- wikimedia-paths-parameter-example-only-ref
- wikimedia-requestbody-example-exists
- wikimedia-requestbody-example-only-ref
- wikimedia-response-example-exists
- wikimedia-response-example-only-ref
- wikimedia-schema-example-recommended
Other notes:
- Be sure to adjust linter messages accordingly.
- Make sure that the top-level example for a schema isn't treated in the same way (that is, when the top-level example isn't present but all properties in the schema have examples, the linter shouldn't raise an issue).
- This task can likely be completed together with T424002.
To replicate
- Start with the OAD example.
- Modify the example: under the NewPet component in line 1018, remove one of the two example fields in the properties object.
- Lint the modified OAD. Notice that the linting results don't display an issue for the wikimedia-requestbody-example-only-ref rule.
- Modify the example: under the same component, remove the other example field so that there are no examples for any properties listed in the NewPet component.
- Lint the modified OAD again. Notice that wikimedia-requestbody-example-only-ref now appears on the list of issues and the linter now displays the correct message: "Request body schema uses a $ref without explicit examples. Verify that the referenced schema defines examples." (In fact this happens twice because the OAD references the same component in two places).