Skip to content

/ OpenAPI-Specification

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Examples table with confusing notes #2088

Open
hrennau opened this issue Jan 7, 2020 · 1 comment
Open

Examples table with confusing notes #2088

hrennau opened this issue Jan 7, 2020 · 1 comment
Labels
Minor Change

Comments

@hrennau
Copy link

@hrennau hrennau commented Jan 7, 2020

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
Copy link
Contributor

@tedepstein tedepstein commented Feb 24, 2020 •
edited

@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
... ... ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Minor Change
Projects
None yet
Milestone
No milestone
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
@tedepstein @hrennau
You can’t perform that action at this time.