capabilities documentation #296
Conversation
Co-authored-by: Ralf Handl <[email protected]>
…ng the dollar symbol ($)
… incorrect transformation of URLs
* Drafted component to interactively make queries within documentation * Styled results to be a scrollable box * Created function to format queries so they work regardless of including the dollar symbol ($) * addressed bugs/errors related to requests on unmounted components and incorrect transformation of URLs * added interactive querying for all examples * improved accuracy and efficiency of reformatting queries * cleaned up code and added method comment * reformatted query and results * integrated intellisense query component * reformatted/removed old version of template/example queries * made stylistic changes to fonts, buttons, etc. * implemented better responsivity with scrolling of query editor; documented code * fixed parsing of JSON results * Fixed occasional bug with rendering results by changing results format for CodeBlock * removed unnecessary console log
| | text | `<string op>(<property>, <literal>)`,<br/>where `<string op>` is one of `startswith`, `endswith`, `contains` | | ||
| | any | any expression including expressions combined with `not`, `and`, and `or` | | ||
|
|
||
| In RSDL this |
There was a problem hiding this comment.
Sentence looks incomplete
| filter { | ||
| eq { id name description createdDate fulfillmentDate } | ||
| ranges { createdDate description } | ||
| prefix { name } | ||
| text { description } | ||
| } | ||
|
|
||
| filter { | ||
| eq except { description } | ||
| ranges { createdDate description } | ||
| prefix { name } | ||
| text { description } | ||
| } |
There was a problem hiding this comment.
Really two occurrences of filter {...}? Or should these be two separate examples?
| traits { | ||
| longRunningOperation | ||
| topWithoutSkip | ||
| throttling { level: "premium\u12a4" } |
There was a problem hiding this comment.
Are the values always strings, or can they also be arrays, objects, numbers, booleans, i.e. "embedded JSON"?
| targets: /orders | ||
| targets: unbound | ||
| # 'targets' ':' ( path / 'unbound' ) |
There was a problem hiding this comment.
targets sounds like plural: better use target?
| query-capabilities = [ expand-capabilities ] / | ||
| [ filter-capabilities ] / [ select-capabilities ] / | ||
| [ paging-capabilities ] / [ count-capabilities ] / |
There was a problem hiding this comment.
Better move after delete-capabilities for "hierarchical reading".
| ```xml | ||
| <Annotations Target="skus"> | ||
| <Annotation Term="Org.OData.Capabilities.V1.DeleteRestrictions"> | ||
| <Record Type="Org.OData.Capabilities.V1.DeleteRestrictionsType"> | ||
| <PropertyValue Property="Deletable" Bool="true" /> | ||
| </Record> | ||
| </Annotation> | ||
| </Annotations> | ||
| ``` |
There was a problem hiding this comment.
Actually we need to produce the complement, i.e. Deletable: false for all service members that have no path allowing DELETE, same for all other "default" capabilities.
| <Annotations Target="skus"> | ||
| <Annotation Term="Org.OData.Capabilities.V1.UpdateRestrictions"> | ||
| <Record Type="Org.OData.Capabilities.V1.UpdateRestrictionsType"> | ||
| <PropertyValue Property="Updatable" Bool="true" /> |
There was a problem hiding this comment.
| <PropertyValue Property="Updatable" Bool="true" /> |
"true" is the default
There was a problem hiding this comment.
I am ok to not generate it but would suggest to keep it here to make it explicit.
If you think this is too distracting I might change it to a comment
<!-- by default <PropertyValue Property="Updatable" Bool="true" /> -->Thoughts?
There was a problem hiding this comment.
You can leave it in the generated output, but I'd remove it from the documentation as it has no effect.
| <Annotations Target="orders"> | ||
| <Annotation Term="Org.OData.Capabilities.V1.InsertRestrictions"> | ||
| <Record Type="Org.OData.Capabilities.V1.InsertRestrictionsType"> | ||
| <PropertyValue Property="Insertable" Bool="true" /> |
There was a problem hiding this comment.
| <PropertyValue Property="Insertable" Bool="true" /> |
| ```xml | ||
| <Annotations Target="skus"> | ||
| <Annotation Term="Org.OData.Capabilities.V1.TopSupported" Bool="true" /> | ||
| <Annotation Term="Org.OData.Capabilities.V1.SkipSupported" Bool="true" /> | ||
| </Annotations> | ||
| ``` |
There was a problem hiding this comment.
Again: this is the default, need to opt out of paging
There was a problem hiding this comment.
I need to think a little but about generating this (or to be precise generating the false for the GET requests that do not contain paging
| "orders": { | ||
| "@Org.OData.Capabilities.V1.FilterRestrictions": { | ||
| "$Type": "Org.OData.Capabilities.V1.FilterRestrictionsType", | ||
| "Filterable": true, |
There was a problem hiding this comment.
| "Filterable": true, |
| "Filterable": true, | ||
| "FilterExpressionRestrictions": [ | ||
| { | ||
| "$Type": "Org.OData.Capabilities.V1.FilterExpressionRestrictionType", |
There was a problem hiding this comment.
| "$Type": "Org.OData.Capabilities.V1.FilterExpressionRestrictionType", |
Actually you'd have to produce
"@odata.type":"https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.json#Org.OData.Capabilities.V1.FilterExpressionRestrictionType"There was a problem hiding this comment.
I am not 100% sure I understand the details. Are you referring to The type of a record expression is represented as the @type control information, see
I would really like to understand the exact details on how this has to look because this is not directly generated by me but through the odata .net library which has to be fixed to serialize this correctly into JSON.
Any pointers would be appreciated.
There was a problem hiding this comment.
Yes, and example 86:
"@person.Employee": {
"@type": "https://example.org/vocabs/person#org.example.person.Manager",The form is <URL to CSDL document>#<qualified name of type>, see OData JSON Format, 4.5.3 Control Information: type (odata.type).
| ```xml | ||
| <Annotations Target="orders"> | ||
| <Annotation Term="Org.OData.Capabilities.V1.ExpandRestrictions"> | ||
| <Record Type="Org.OData.Capabilities.V1.ExpandRestrictionsType"> | ||
| <PropertyValue Property="Expandable" Bool="true" /> | ||
| </Record> | ||
| </Annotation> | ||
| </Annotations> | ||
| <Annotations Target="orders/items"> | ||
| <Annotation Term="Org.OData.Capabilities.V1.ExpandRestrictions"> | ||
| <Record Type="Org.OData.Capabilities.V1.ExpandRestrictionsType"> | ||
| <PropertyValue Property="Expandable" Bool="true" /> | ||
| </Record> | ||
| </Annotation> | ||
| </Annotations> | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Again we'll have to express the expand restrictions, and the new target syntax is not (yet) recognized by any tools.
What the OpenAPI generator already recognizes is this syntax:
https://github.com/oasis-tcs/odata-openapi/blob/15220b9a26a2e6c40ad4dd57e1712f275d23b08d/test/csdl2openapi.test.js#L1983-L1990
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
docs/rsdl/rapid-rsdl-capabilities.md
docs/rsdl/rapid-rsdl-capability-mapping.mdx