[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: Agenda for OData TC meeting on 2019-01-10
Rough minutes copied from chat:
Attendees: Mark Biamonte
Matthew Borges
George Ericson
Hubert Heijkers
Ted Jones
Saurabh Madan
Michael Pizzo
Mike Pizzo: Agenda approved Mike Pizzo: a.Minutes from December 20, 2018 TC meeting: https://www.oasis-open.org/committees/download.php/64481/odata-meeting-241_on-20181220-minutes.html Mike Pizzo: Minutes approved -- thanks Stefan! Mike Pizzo: 4.Review action items [Action item list: https://www.oasis-open.org/apps/org/workgroup/odata/members/action_items.php?sort_field=due_closed_date] [8:15am PT] a.Upcoming
i.#0037 Concept for Google Protocol Buffers as a data format Hubert Heijkers 2019-03-28
b.In progress
i.#0036 Register the OData- headers and preferences with IANA Mark Biamonte 2018-07-26
1.Feedback from Mark Nottingham, 2019-01-03, on the header OData-Isolation:
My .02 - If it were me, I'd just register OData-Isolation, because in my experience, things that are defined without having multiple communities tend to miss the requirements that other communities have, so they don't get used.
Colloquially, we call this "hope-based standardisation" -- it's sometimes appropriate, but it requires some amount of engagement/research, and from what I can see you don't have that here. If other folks with REST APIs have requirements along these lines, they can learn from your experiences, have their discussions, and mint a new header that they can use, rather than trying to fit their use cases into what you've sketched out.
2.Feedback from Mark Nottingham, 2019-01-03, on the preferences:
See also my note just now about optimistic standardisation; personally, I tend to think that registering the OData-* prefixed versions is the right thing to do here.
Mike Pizzo: Two reasons for proposing the non-OData forms: Mike Pizzo: 1) so that others could use them, and Mike Pizzo: 2) So that we could define a lightweight "REST-EZ" profile that didn't have the "OData" name in the options Mike Pizzo: Mark: we could consider standardizing the OData versions and use the non-OData ones without registering Mike Pizzo: Question: what is the benefit of registering headers and preferences? One obvious is avoiding collision, which can be achieved through prefixing with OData. The other would be for sharing, but if Mark is advocating against hope-based standardization, then it would only make sense to publish if already jointly used. Mike Pizzo: Mike to follow up on the benefit of registering these preferences Mike Pizzo: Propose: not make any changes to our spec at this point; keep both the odata prefixed and non-prefixed names for now, and follow up with chet/mark on value of registering and ramifications of not registering these common forms. Mike Pizzo: i.ODATA-1268 Clarify meaning of Nullable for collection-valued structural properties Mike Pizzo: Current wording in CSDL-JSON: A Boolean value specifying whether a value is required for the property.
$Nullable
The value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.
Mike Pizzo: In XML CSDL: Mike Pizzo: A Boolean value specifying whether a value is required for the property. Attribute Nullable
The value of Nullable is one of the Boolean literals true or false.
If no value is specified for a single-valued property, the Nullable attribute defaults to true.
In OData 4.01 responses a collection-valued property MUST specify a value for the Nullable attribute.
If no value is specified for a collection-valued property, the client cannot assume any default value. Clients SHOULD be prepared for this situation even in OData 4.01 responses.
Mike Pizzo: In return type, we have the following wording: For collection-valued return types the result will always be a collection that MAY be empty. In this case the Nullable attribute applies to items of the collection and specifies whether the collection MAY contain null values.
Mike Pizzo: In proposal, change "For collection-valued parameters the property value will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values." to "For collection-valued properties the property value will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values." Mike Pizzo: This could also apply to a function/action that returns a collection of entity types, where the returned collection could contain null values. Mike Pizzo: It would not apply to a navigation property or entity set, as we don't have the concept of a null value in either of those. Mike Pizzo: (That is, it would not apply to a collection-valued navigation property, or an entity set...) Mike Pizzo: ODATA-1268 is open. Mike Pizzo: Updated proposal: $Nullable
The value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.
For single-valued properties the value true means that the property allows the null value.
For collection-valued properties the property value will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.
Hubert Heijkers (IBM): I move to resolve ODATA-1268 as per the updated proposal. Mark Biamonte (Progress): I second Mike Pizzo: OData-1268 is resolved as proposed. Mike Pizzo: ii.ODATA-1265 Clarify property paths used in a lambda predicate _expression_ Mike Pizzo: Opened by Gerald. Postpone discussion until he can join to discuss. Mike Pizzo: iii.ODATA-1257 Do URLs within a Batch Request need to be URL Encoded? Mark Biamonte (Progress): The syntax for a URI is defined in RFC 3986 Uniform Resource Identifier (URI): Generic Syntax. In that document the query component is defined to begin with the first question mark (?) character and end with either the hash (#) character or the end of the URI. The BNF for the contents of the query component is query = *( pchar / "/" / "?" )
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
pct-encoded = "%" HEXDIG HEXDIG
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
reserved = gen-delims / sub-delims
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
From this part of the spec, colons in a query string are valid and do not need to be percent encoded. The prose text in the Reserved Characters section states
URI producing applications should percent-encode data octets that
correspond to characters in the reserved set unless these characters
are specifically allowed by the URI scheme to represent data in that
component. If a reserved character is found in a URI component and
no delimiting role is known for that character, then it must be
interpreted as representing the data octet corresponding to that
character's encoding in US-ASCII.
The colon character is a reserved character, but it is explicitly listed in the query component rule so it should not need to be percent encoded. That is my interpretation of the spec. Also, since implementations didnt always follow the specs in the past I did try submitting requests to our service using Chrome, Microsoft Edge and Postman. In each of those cases they encoded the spaces and quotes in the query string, but did not encode the colon character. I also tried submitting the request with Fiddler and it did not need the colon character encoded to submit the request. So all of the implementations that I have access to do not encode the colon character
Mike Pizzo: Here is the current wording in the proposal: URLs must be fully percent encoded in the request, including in a multipart batch request
URLs represented as string within a JSON payload, including JSON batch, must be safely encoded. Need to define what safely encoded means - colons within the path must be encoded, (and forward-slashes used within data values) percent-encoded. Question marks within path must be encoded, and hashes must be encoded.
Question: must colons in query string be percent-encoded?
Mike Pizzo: Answer (based on Mark's research) no, colons in the query string should not need to be percent encoded. Mike Pizzo: Revised proposal: URLs must be fully percent encoded in the request, including in a multipart batch request
URLs represented as string within a JSON payload, including JSON batch, must be safely encoded. Colons, forward-slashes, hashes, and question marks used in data values within path must be encoded, and hashes must be encoded.
Colons in the query string do not need to be percent encoded.
Mike Pizzo: Hubert: no additional rules for representing the URL in a JSON payload versus as a request. Mike Pizzo: URLs must be fully percent encoded in the request, including in a multipart batch request URLs represented as string within a JSON payload, including JSON batch, must follow standard OData encoding rules, which do not require that colons in the query string be percent encoded.
Hubert Heijkers (IBM): I move to resolve ODATA-1257 as per the amended proposal Mark Biamonte (Progress): I second Mike Pizzo: ODATA-1257 is resolved as per the amended proposal. Mike Pizzo: 6.Review Permissions annotations [9:30 am PT] Mike Pizzo: Auth flows are defined using a named auth scheme. Mike Pizzo: A named auth scheme can enumerate the scopes that are available through that auth scheme. Mike Pizzo: When authenticating, the client requests some set of scopes that are available through that auth scheme. Mike Pizzo: The Permissions vocabulary attempts to specify what is available for a given scope. Mike Pizzo: i.e., given a scope, what can I read, create, update, or delete. Mike Pizzo: Permissions are added to insert restrictions, update restrictions, delete restrictions, and read restrictions, as well as the corresponding navigation property restrictions, to specify what permissions are required for each of those actions against an entity. Mike Pizzo: The permission references a named auth flow, and lists the permissions from that auth flow grant access to the resource. Mike Pizzo: The permission can also call out property restrictions that define properties that require additional scopes. Mike Pizzo: Comment: we need a way to specify that some properties are not accessible at all given a particular auth scheme (perhaps null for the scope name? Mike Pizzo: 7.Next meetings [9:50 am PT] a.Thursday January 17, 2019 during 8-10 am PST (17:00-19:00 CET)
b.Thursday January 24, 2019 during 8-10 am PST (17:00-19:00 CET)
Mike Pizzo: George has a conflict next week. Mike Pizzo: We'll need someone to fill in for secretary next week. Mike Pizzo: 8.AOB and wrap up [9:55 am PT] From: odata@lists.oasis-open.org <odata@lists.oasis-open.org>
On Behalf Of Michael Pizzo Here [1] is a draft agenda for the OData TC (Technical Committee) meeting
scheduled on
Thursday January 10, 2019 during 8-10 am PST (17:00-19:00 CET).
For additional information, such as dial-in details and chat room, refer to [2]. For TC timeline, see [3]. Feel free to suggest additions or modifications.
Thanks.
[1]
Agenda
1.
Roll call [8:00 am PT]
2.
Approve agenda [8:05 am PT]
3.
Approve minutes from previous meeting(s) [8:10 am PT]
4.
Review action items [Action item list:
https://www.oasis-open.org/apps/org/workgroup/odata/members/action_items.php?sort_field=due_closed_date] [8:15am PT]
i. #0037
Concept for Google Protocol Buffers as a data format – Hubert Heijkers – 2019-03-28
i. #0036
Register the OData- headers and preferences with IANA – Mark Biamonte – 2018-07-26
My .02 - If it were me, I'd just register OData-Isolation, because in my experience, things that are defined without having multiple communities tend
to miss the requirements that other communities have, so they don't get used. Colloquially, we call this "hope-based standardisation" -- it's sometimes appropriate, but it requires some amount of engagement/research, and from
what I can see you don't have that here. If other folks with REST APIs have requirements along these lines, they can learn from your experiences, have their discussions, and mint a new header that they can use, rather than trying to fit their use cases into
what you've sketched out.
See also my note just now about optimistic standardisation; personally, I tend to think that registering the OData-* prefixed versions is the right
thing to do here.
5.
Issues [8:20 am PT]
i. ODATA-1268
Clarify meaning of Nullable for collection-valued structural properties
ii. ODATA-1265
Clarify property paths used in a lambda predicate _expression_
iii. ODATA-1257
Do URLs within a Batch Request need to be URL Encoded?
iv. ODATA-1263
Requirement for 204 (No Content) with 11.4.3 "Update an Entity" is not backwards compatible
v. ODATA-1261
Allow $pagesize system query option
vi. ODATA-1260
Clarify read-write access via URLs differing from the canonical/read/edit URL
vii. ODATA-1259
Clarify @type (@odata.type) and metadata=full
viii. ODATA-1266
Geo literals with three dimensions
ix. ODATA-1250
GeoJSON, SRID, and LineString
x. ODATA-1243
Clarify whether $orderby and string comparison with ge, gt, le, lt is language-specific
xi. ODATA-1242
Clarify that resolved relative URIs in batch responses cannot contain content-ID references
xii. ODATA-1226
Ambiguity with Capabilities.ChangeTracking annotation
xiii. ODATA-1177
Add "JSON properties" to OData
xiv. ODATA-1262
Explicitly state structural restrictions of type Edm.Untyped
xv. ODATA-1165
Describe $expand and $select via prose text and examples, remove ABNF snippets
xvi. ODATA-1267
URL Conventions example in 5.1.1.5.1 has "bad" whitespace
xvii. ODATA-1253
Abstract type definition Core.Number as a super-type of all numeric types
xviii. ODATA-1246
Allow BaseType to be a ComplexType
xix. ODATA-1239
Define a mechanism to distinguish between inserted and updated entities in a Delta Response
xx. ODATA-1238
Clarifications for select-list in ContextUrl
xxi. ODATA-1198
ETag handling deviations from RFC7232 are avoidable if we consider two kinds of ETag (ETag in response header and ETag in response payload)
xxii. ODATA-1168
Clarify the use of ETags for Avoiding Update Conflicts
xxiii. ODATA-1135
Document use of JSON $schema
xxiv. ODATA-1064
Add ability to annotate collections to return only count and NextLink
xxv. ODATA-1005
Make sure we have capabilities for all new 4.01 functionality
i. ODATA-1256
Harmonize usage of custom aggregates with structured aggregatable properties
ii. ODATA-1244
Add a function to determine aggregated values within common expressions
iii. ODATA-1218
Transformations for recursive hierarchy processing
iv. ODATA-1207
Clarify need for @odata.id in nested response structures
v. ODATA-945
Correct examples 53 and 54
i. ODATA-1176
Capabilities: add new term SelectSupport
ii. ODATA-1099
Add annotations to describe custom query options and custom headers
i. ODATA-1264
CRUD descriptions on entity sets
ii. ODATA-1214
Annotate constructor actions
iii. ODATA-1140
ODATA-884 / Add details to HTTPResponseCode term
iv. ODATA-1107
Introduce instance annotation to specify which types an instance "implements"
v. ODATA-1060
Improve specification of element response requirements
vi. ODATA-884
Enable enumerating the valid requests and responses for a particular resource.
6.
Review Permissions annotations [9:30 am PT]
7.
Next meetings [9:50 am PT]
8.
AOB and wrap up [9:55 am PT] [2]
References
[3]
Timeline |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]