Skip to content
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.

Sign up for GitHub

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

Don't encode %24 in docs #1149

Merged
merged 3 commits into from
Jun 3, 2024
Merged

Don't encode %24 in docs #1149

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d52d790
Don't escape $
lognaturel May 31, 2024
c1d479d
Remove redundant enum values and ignored properties
lognaturel May 31, 2024
eb8c838
Bring back siblings to
lognaturel Jun 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 29 additions & 40 deletions docs/api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2263,8 +2263,6 @@ paths:
content:
application/json:
schema:
type: object
description: Standard Response
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More of a question than anything else, but I don't see a top-level description in the Project schema. Did you remove it here because it just doesn't add much? Have you noticed any trend whereby we should generally be adding description in more places or removing it in more places?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should have explained this, sorry. I used https://editor-next.swagger.io/ to see whether the $ might give a syntax error because I thought that might be what the encoding was about. It turns out there are some not small number of errors so I started picking off a couple thinking maybe more would show up at the bottom. That wasn't the case but I committed these anyway.

Those siblings of $ref are ignored by standards-compliant tools. I now realize that our target client is our own docs which are not really spec-compliant so we can keep this and it will get rendered.

I feel so much empathy for the folks dealing with this seemingly-simple limitation that is made difficult to address because of broader specifications. OAI/OpenAPI-Specification#1514 swagger-api/swagger-editor#1184

$ref: '#/components/schemas/Project'
example:
id: 1
Expand All @@ -2274,8 +2272,6 @@ paths:
archived: false
application/json; extended:
schema:
type: object
description: Extended Response
$ref: '#/components/schemas/ExtendedProjectWithVerbs'
example:
id: 1
Expand Down Expand Up @@ -2342,9 +2338,8 @@ paths:
forms:
type: array
description: If given, the Form metadata to update.
items: {
items:
type: object
}
example:
name: New Project Name
description: New Project Description
Expand Down Expand Up @@ -5704,7 +5699,6 @@ paths:
- hasIssues
- rejected
- approved
- approved
createdAt:
type: string
description: ISO date format. The time that the server received
Expand Down Expand Up @@ -5984,7 +5978,6 @@ paths:
- hasIssues
- rejected
- approved
- approved
createdAt:
type: string
description: ISO date format. The time that the server received
Expand Down Expand Up @@ -6159,7 +6152,6 @@ paths:
- hasIssues
- rejected
- approved
- approved
createdAt:
type: string
description: ISO date format. The time that the server received
Expand Down Expand Up @@ -6358,7 +6350,7 @@ paths:
schema:
type: boolean
example: "true"
- name: '%24filter'
- name: '$filter'
in: query
description: If provided, will filter responses to those matching the given
OData query. Only [certain fields](/central-api-odata-endpoints/#data-document)
Expand Down Expand Up @@ -6461,7 +6453,7 @@ paths:
schema:
type: boolean
example: "true"
- name: '%24filter'
- name: '$filter'
in: query
description: If provided, will filter responses to those matching the given
OData query. Only [certain fields](/central-api-odata-endpoints/#data-document)
Expand Down Expand Up @@ -6561,7 +6553,7 @@ paths:
schema:
type: string
example: simple
- name: '%24filter'
- name: '$filter'
in: query
description: If provided, will filter responses to those matching the given
OData query. Only [certain fields](/central-api-odata-endpoints/#data-document)
Expand Down Expand Up @@ -6630,7 +6622,7 @@ paths:
schema:
type: string
example: simple
- name: '%24filter'
- name: '$filter'
in: query
description: If provided, will filter responses to those matching the given
OData query. Only [certain fields](/central-api-odata-endpoints/#data-document)
Expand Down Expand Up @@ -7778,7 +7770,6 @@ paths:
- hasIssues
- rejected
- approved
- approved
createdAt:
type: string
description: ISO date format. The time that the server received
Expand Down Expand Up @@ -8112,7 +8103,6 @@ paths:
- hasIssues
- rejected
- approved
- approved
createdAt:
type: string
description: ISO date format. The time that the server received
Expand Down Expand Up @@ -8251,7 +8241,6 @@ paths:
- hasIssues
- rejected
- approved
- approved
createdAt:
type: string
description: ISO date format. The time that the server received
Expand Down Expand Up @@ -10499,7 +10488,7 @@ paths:

Please see the [OData documentation](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948) on `$filter` [operations](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinFilterOperations) and [functions](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinQueryFunctions) for more information.

As of ODK Central v1.2, you can use `%24expand=*` to expand all repeat repetitions. This is helpful if you'd rather get one nested JSON data payload of all hierarchical data, rather than retrieve each of repeat as a separate flat table with references.
As of ODK Central v1.2, you can use `$expand=*` to expand all repeat repetitions. This is helpful if you'd rather get one nested JSON data payload of all hierarchical data, rather than retrieve each of repeat as a separate flat table with references.

The _nonstandard_ `$wkt` querystring parameter may be set to `true` to request that geospatial data is returned as a [Well-Known Text (WKT) string](https://en.wikipedia.org/wiki/Well-known_text) rather than a GeoJSON structure. This exists primarily to support Tableau, which cannot yet read GeoJSON, but you may find it useful as well depending on your mapping software. **Please note** that both GeoJSON and WKT follow a `(lon, lat, alt)` coördinate ordering rather than the ODK-proprietary `lat lon alt`. This is so that the values map neatly to `(x, y, z)`. GPS accuracy information is not a part of either standards specification, and so is presently omitted from OData output entirely. GeoJSON support may come in a future version.

Expand Down Expand Up @@ -10537,35 +10526,35 @@ paths:
schema:
type: string
example: Submissions
- name: '%24skip'
- name: '$skip'
in: query
description: If supplied, the first `$skip` rows will be omitted from the
results.
schema:
type: number
example: "10"
- name: '%24top'
- name: '$top'
in: query
description: If supplied, only up to `$top` rows will be returned in the results.
schema:
type: number
example: "5"
- name: '%24count'
- name: '$count'
in: query
description: If set to `true`, an `@odata.count` property will be added to
the result indicating the total number of rows, ignoring the above paging
parameters.
schema:
type: boolean
example: "true"
- name: '%24wkt'
- name: '$wkt'
in: query
description: If set to `true`, geospatial data will be returned as Well-Known
Text (WKT) strings rather than GeoJSON structures.
schema:
type: boolean
example: "true"
- name: '%24filter'
- name: '$filter'
in: query
description: If provided, will filter responses to those matching the query.
Only [certain fields](/central-api-odata-endpoints/#data-document)
Expand All @@ -10575,26 +10564,26 @@ paths:
schema:
type: string
example: year(__system/submissionDate) lt year(now())
- name: '%24orderby'
- name: '$orderby'
in: query
description: If provided, will sort responses according to specified order expression. Only the same fields as `$filter` above can be used to sort. Multiple expressions can be used together.
schema:
type: string
example: __system/submitterId asc, __system/updatedAt desc
- name: '%24expand'
- name: '$expand'
in: query
description: Repetitions, which should get expanded. Currently, only `*` is
implemented, which expands all repetitions.
schema:
type: string
example: '*'
- name: '%24select'
- name: '$select'
in: query
description: If provided, will return only the selected fields.
schema:
type: string
example: __id, age, name, meta/instanceID
- name: '%24skiptoken'
- name: '$skiptoken'
in: query
description: Opaque cursor from `@odata.nextLink` used for paging.
schema:
Expand Down Expand Up @@ -11062,28 +11051,28 @@ paths:
schema:
type: string
example: people
- name: '%24skip'
- name: '$skip'
in: query
description: If supplied, the first `$skip` rows will be omitted from the
results.
schema:
type: number
example: "10"
- name: '%24top'
- name: '$top'
in: query
description: If supplied, only up to `$top` rows will be returned in the results.
schema:
type: number
example: "5"
- name: '%24count'
- name: '$count'
in: query
description: If set to `true`, an `@odata.count` property will be added to
the result indicating the total number of rows, ignoring the above paging
parameters.
schema:
type: boolean
example: "true"
- name: '%24filter'
- name: '$filter'
in: query
description: If provided, will filter responses to those matching the query.
Only [certain fields](/central-api-odata-endpoints/#data-document)
Expand All @@ -11093,19 +11082,19 @@ paths:
schema:
type: string
example: year(__system/createdAt) lt year(now())
- name: '%24orderby'
- name: '$orderby'
in: query
description: If provided, will sort responses according to specified order expression. Only the same fields as `$filter` above can be used to sort. Multiple expressions can be used together.
schema:
type: string
example: __system/creatorId asc, __system/updatedAt desc
- name: '%24select'
- name: '$select'
in: query
description: If provided, will return only the selected fields.
schema:
type: string
example: __id, label, name
- name: '%24skiptoken'
- name: '$skiptoken'
in: query
description: Opaque cursor from `@odata.nextLink` used for paging.
schema:
Expand Down Expand Up @@ -11485,35 +11474,35 @@ paths:
schema:
type: string
example: Submissions
- name: '%24skip'
- name: '$skip'
in: query
description: If supplied, the first `$skip` rows will be omitted from the
results.
schema:
type: number
example: "10"
- name: '%24top'
- name: '$top'
in: query
description: If supplied, only up to `$top` rows will be returned in the results.
schema:
type: number
example: "5"
- name: '%24count'
- name: '$count'
in: query
description: If set to `true`, an `@odata.count` property will be added to
the result indicating the total number of rows, ignoring the above paging
parameters.
schema:
type: boolean
example: "true"
- name: '%24wkt'
- name: '$wkt'
in: query
description: If set to `true`, geospatial data will be returned as Well-Known
Text (WKT) strings rather than GeoJSON structures.
schema:
type: boolean
example: "true"
- name: '%24filter'
- name: '$filter'
in: query
description: If provided, will filter responses to those matching the query.
Only [certain fields](/central-api-odata-endpoints/#data-document)
Expand All @@ -11523,14 +11512,14 @@ paths:
schema:
type: string
example: year(__system/submissionDate) lt year(now())
- name: '%24expand'
- name: '$expand'
in: query
description: Repetitions, which should get expanded. Currently, only `*` is
implemented, which expands all repetitions.
schema:
type: string
example: '*'
- name: '%24select'
- name: '$select'
in: query
description: If provided, will return only the selected fields.
schema:
Expand Down