I’ve noticed that the linter rules currently check examples only at the object level. While this is useful for overall consistency, there are scenarios where property-level example validation would be beneficial. Specifically, I’d like to propose an enhancement that allows to validate examples associated with individual properties within an OpenAPI document.
Use Case: Consider the following situation:
- An API specification contains multiple properties within an object.
- Each property has its own example value.
- Some properties are defined globally and have their own property-specific example attached (e.g. 'createdAt' or 'updatedAt' attributes).
Expected Behavior: I suggest extending the rule to validate examples at both the object level and the property level. This enhancement would provide more granular control over example validation.
Benefits:
- Fine-Grained Validation: Property-level example checks would help maintain consistency within individual properties
- Improved API Quality: By validating property-level examples, we can support to reference properties which are used in multiple object without specify the relevant examples again for each occurrence
Example: Suppose we have an OpenAPI schema like this:
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/demo:
get:
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Demo'
components:
schemas:
timestamp:
type: string
format: date-time
readOnly: true
description: >
This value is auto generated by the API [RFC 3339, section
5.6/ISO8601](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)
example: '2022-09-25T10:43:28.000Z'
Demo:
type: object
properties:
id:
type: string
description: ID of the source
example: ce49715f-784b-45fd-b6c4-56f8435237a2
createdAt:
$ref: '#/components/schemas/timestamp'
updatedAt:
$ref: '#/components/schemas/timestamp'
I’ve noticed that the linter rules currently check examples only at the object level. While this is useful for overall consistency, there are scenarios where property-level example validation would be beneficial. Specifically, I’d like to propose an enhancement that allows to validate examples associated with individual properties within an OpenAPI document.
Use Case: Consider the following situation:
Expected Behavior: I suggest extending the rule to validate examples at both the object level and the property level. This enhancement would provide more granular control over example validation.
Benefits:
Example: Suppose we have an OpenAPI schema like this: