json schema for binary (such as an image)

[Ning]

Is it possible/appropriate to describe an image using json schema? 

It is kind of awkward since a binary is not a json instance.

[Austin Wright]

It's not really possible to encode binary data natively in JSON (being Unicode), you either need an array or a base64-encoded string.

These would look like:

{type:"array", items:{type:"integer"}}

or

{type:"string", format:"base64"}

[Geraint]

Actually - this kind of thing is exactly what the "media" keyword is for.

In fact the example in the spec (http://json-schema.org/latest/json-schema-hypermedia.html#anchor10) is a schema representing a base64-encoded PNG image.

{
    "type": "string",
    "media": {
        "binaryEncoding": "base64",
        "type": "image/png"
    }
}

The example in the overview section also includes a base64-encoded PNG as a property of a larger object.

I hope that helps.

[Geraint]

If you're actually looking to describe non-JSON data, then there's nothing in JSON Schema for that.

What's your use-case for this?  Are you trying to embed an image in a larger document (encoded as a string, as described previously), or describing the target format of a link (you can use the "mediaType" property of LDOs for that), or specifying that an image should be uploaded to a particular URL?

[Ning]

We have both use cases. Depending on where the binary is located, sometimes it is possible/easier to embed it as part of the owning json document, sometimes we only include a link to it. 

It is understood that I can provide the target format for the link in the hyper media part. 

There is another use case, which is probably not very common: a binary itself is a standalone resource. It is not embedded as part of an owning object. Since we don't want to invent something else to describe it, it is better to use json schema for everything. In that case, there is no property really. I guess I could still provide the links in the hyper media part, such as a link for GET, another link for PUT, etc. 

[Geraint]

On Thursday, April 25, 2013 10:01:14 PM UTC+1, Ning wrote:

We have both use cases. Depending on where the binary is located, sometimes it is possible/easier to embed it as part of the owning json document, sometimes we only include a link to it. 

It is understood that I can provide the target format for the link in the hyper media part. 

Sounds like you're covered for these two - for links pointing to images, you can specify the expected target media type (e.g. "image/png") using the "mediaType" property of the link definition, and for embedded images you can use the "media" keyword in the schema.

 

There is another use case, which is probably not very common: a binary itself is a standalone resource. It is not embedded as part of an owning object. Since we don't want to invent something else to describe it, it is better to use json schema for everything. In that case, there is no property really. I guess I could still provide the links in the hyper media part, such as a link for GET, another link for PUT, etc. 

The reason that JSON Schema needs to exist is that JSON data can be wildly different structures - just describing it as "application/json" doesn't give enough information.

However for formats such as PNG, the media type (e.g. "image/png") is sufficient to parse and display the information.  So why do you need a schema to describe it?  If you're serving the images over HTTP, "Content-Type" can completely describe the format - and you can even specify some link information for the images using the HTTP "Link" header.  What more are you looking to describe?

[Ning]

We are looking at one way of describing all the resources, and see if json schema is sufficient to cover all cases. I know it is kind of weird because the resource is not even a json object.

[Geraint Luff]

Could you use "image/png" for the images, and use "application/json; profile=/schemas/whatever" for the JSON?

That way you can describe all the resources, while still making use of JSON Schema for describing the JSON data by referencing particular schemas, so you can do more advanced processing based on those schemas.

You'd more or less be emulating the "Content-Type" HTTP header - but frankly I think it's a pretty good resource format indicator, especially if you include the JSON Schema "profile=" parameter.

--
You received this message because you are subscribed to a topic in the Google Groups "JSON Schema" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/json-schema/_LjvUe2V3mc/unsubscribe?hl=en-US.
To unsubscribe from this group and all its topics, send an email to json-schema...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Austin Wright]

In a good HTTP API, you probably want each image to get its own URI. If you want to download a number of images, you might consider multipart/form-data encoding to request many of these resources in a single GET request, and use the Content-Location header in each form-data part to describe the URI of each image within the response. Or just send back a tar file, and use the filenames to describe a relative URI.

Once you have these images accessible through HTTP, then you can refer to them by their URI inside the JSON file.

In any event, embedding images in JSON probably isn't the best idea. In the instances where it does make sense, consider the "media" property as already described.