Improve linting of examples defined in `schema.properties`.
##Implementation update
We decided as a team to include any of the remaining work in {T426836} within the implementation of this task, {T424002}, and to decline {T426836}.
##Background
Example detection described in T423411 provides rules for identifying whether a parameter, request body, response, or a schema has an example listed in schema properties:
- for parameters:
- `[parameter].schema.properties.[every individual property].example`
- `[parameter].content.[media object].schema.properties.[every individual property].example`
- for request bodies:
- `requestBody.content.[media object].schema.properties.[every individual property].example`
- for responses:
- `[response].content.[media object].schema.properties.[every individual property].example`
- for `components.schema`:
- `schema.properties.[every individual property].example`
This description already suggests that for a given parameter, request body, response, or schema, we consider it to //have an example// (and thus not raise a warning), when all the properties in `schema.properties` have an example. For example, like in:
```
requestBody:
description: Pet to add to the system
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: Pet name
example: Haru # <-- Property example
tag:
type: string
enum:
- cat
- dog
- fish
description: Pet type or category
example: cat # <-- Property example
```
However, this doesn't make clear that individual properties can themselves be objects, which in turn have properties that may or may not have their own examples. The purpose of this task is to account for this use case.
##Conditions of acceptance
When validating the fields below, only consider all properties to have examples if the entire subtree of properties has examples. This applies to checks for:
- `[parameter].schema.properties.[every individual property]`
- `[parameter].content.[media object].schema.properties.[every individual property]`
- `requestBody.content.[media object].schema.properties.[every individual property]`
- `[response].content.[media object].schema.properties.[every individual property]`
- `schema.properties.[every individual property]`
The linter should be able to validate examples in property structures like below:
```
requestBody:
description: Query parameters to use during search
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
example: Haru # <-- example for property `name`
description: Pet name
tag:
type: string
enum:
- cat
- dog
example: cat # <-- example for property `tag`
description: Pet type
nested: # <-- property `nested` doesn't have an `example` field
type: object # checking examples for `nested.properties`
required:
- name
properties:
name:
type: string
example: Haru # <-- example for property `nested.name`
tag:
type: string
enum:
- cat
- dog
example: cat # <-- example for property `nested.tag`
nested-two: # <-- property `nested.nested-two` doesn't have an `example` field
type: object # checking examples for `nested.nested-two.properties`
required:
- name
properties:
name:
type: string
example: Haru # <-- example for property `nested.nested-two.name`
tag:
type: string
enum:
- cat
- dog
example: cat # <-- example for property `nested.nested-two.tag`
nested-three: # <-- property `nested.nested-two.nested-three` has an `example` field
type: object # no need to check properties
required:
- name
example: # <-- example for property `nested.nested-two.nested-three`
name: Haru
tag: cat
properties:
name:
type: string
tag:
type: string
enum:
- cat
- dog
```