-
Notifications
You must be signed in to change notification settings - Fork 63
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
Clarify the usage of base64 encodings in DataSchema/ContentType #912
Comments
+1 |
regarding JSON Schema spec:
|
both terms will be also introduced in the PR #896 |
Thanks, I updated the first comment for clarity. |
I think this approach (option 2) makes sense if the TD reflects a purely defined JSON based API. Otherwise, the question arises why Option 1 would be not sufficient, especially when a single data value (the image) is submitted as a property. I think we should make this very clear in the specification when should be used contentMediaType and contentEncoding. |
I agree and probably we should some practical examples.
The problem with option 1 is that we do not have a clear way of applying DataSchemas on binary data formats like Furthermore, option two might still be applied to different form contentTypes. As hinted by @zolkis in this comment if we define a common mapping for other content types we will be able to use
Notice that the content described by this affordance will be something like the following:
Whereas if the form contentType is
|
Yes, the use of the string type is not reasonable. But why is a |
I think that string needs to be specified since the new keywords apply to the string type. The examples provided here also use string. It would be like saying |
Yes, specifying only form contentType and encoding remain a valid option. Maybe the example above with // image property affordance
"image": {
"description" : "image",
"forms": [
{
"op": "readproperty",
"href": "coaps://mylamp.example.com/lastPicture",
"cov:methodName" : "GET",
"contentType": "image/png",
"contentEncoding": "base64"
}
]
}} However, the issue was only about when a TD designer wants to use DataSchema to model binary data. This way he/she can design more complex scenarios (i.e. a JSON file which has a property that contains an encoded image). So maybe a better example for this feature will be something like the following: // image property affordance
"image": {
"description" : "image",
"type": "object",
"properties": {
"content": {
"type": "string",
"contentMediaType": "image/png",
"contentEncoding": "base64"
},
// .... other properties with image metadata (i.e. size, timestamp etc.)
},
"forms": [
{
"op": "readproperty",
"href": "coaps://mylamp.example.com/lastPicture",
"cov:methodName" : "GET",
"contentType": "application/json"
}
]
}} Nevertheless, it is important to consider that right now without introducing these two new terms we cannot correctly represent these JSON documents (which may exist out there): "WHyTD/LwZqs6rBIG5fXQHaUyA1QEQfZoXVO3FypCwLaRFCLh+EqSbAxXrk5zRx38+SvM7VhtOfn/fmeYf5hleZGlUwipiPchWINy1DBGtlNReVY1UOJTD0R2teohMlE/jO3ipep5xqf5Cqrqw==" |
As is the case with MIME usage, both discrete and multipart usages are legitimate. In my opinion, both examples are equally important. |
regarding the first example from @relu91 I would expect the following form: // image property affordance
"image": {
"description" : "image",
"forms": [
{
"op": "readproperty",
"href": "coaps://mylamp.example.com/lastPicture",
"cov:methodName" : "GET",
"contentType": "image/png;base64"
}
]
}}
|
lets also check https://tools.ietf.org/html/rfc6839 for the correct format |
PR is merged |
This issue is coming from #869 (comment). I decided to bring it up here because it was not so much related to the PR itself but it has some possible hints to improve the specs. I'll summarize it in the following.
Basically, JSONSchema prescribes how to describe binary data using a JSON string. However is not clear how to use this feature on a TD. In the comment, I made two possible options:
First:
Second
As I described in the comment I prefer the second one, because it adds the ability to use the same patterns even with other forms
contentTypes
(as hinted here by @zolkis ). Also, @egekorkan had a positive comment on this on #869 (comment).Consequently, my proposal is to add an example (maybe inspired by the snippet presented above) to describe this feature. It is quite a common pattern on the web to return images in base64 encoding so it might guide TDs designers in the right direction. We could even specifically formalize the usage of
contentMediaType
andcontentEncoding
in StringDataSchema as we are doing forminlenght
,maxLength
andmultipleOf
in #896 .The text was updated successfully, but these errors were encountered: