Examples table with confusing notes

[hrennau]

In the OpenAPI spec, section "Link Object", https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#linkObject

the "Examples" table following after the text "The table below provides examples of runtime expressions and examples of their use in a value:"

contains a confusing "note" in the third row, and I think a "note" is missing in the second row.

Proposed changes: (1) Second row, third column, enter text: "Request headers referenced in an expression MUST be declared in the parameters section of the parent operation (the operation containing the expression) or they cannot be evaluated." (2) Third row, third column change text to: "Request parameters referenced in an expression MUST be declared in the parameters section of the parent operation (the operation containing the expression) or they cannot be evaluated."

[tedepstein]

@hrennau , thanks. A couple of suggestions:

1. I'm not sure it really helps to spell out these two variants of the same rule. I think the rule, as it's currently stated in row 3, covers both cases. It's less verbose, and easier (IMO) for a reader to manage in working memory. Maybe it just needs to be moved up to row 2.
2. The words "parent" and "containing" could be a little misleading, because a Link Object can be defined in /components/links (or any other location) and referenced there from one or more operations. Maybe we would use the term "referring operation" instead.

Source Location	example expression	notes
HTTP Method	$method	The allowable values for the $method will be those for the HTTP operation.
Requested media type	$request.header.accept	Request parameters, including request headers, MUST be declared in the parameters section of the referring operation or they cannot be evaluated.
Request parameter	$request.path.id
...	...	...

[handrews]

I don't understand what's being asked here. Why would we add notes about request parameters to the "Requested media type" row? Also, the actual "Request parameter" row in both 3.0.3 and 3.1.1 already explicitly states that it includes request headers.

[github-actions[bot]]

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.