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.

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

Pattern for when to use URI string or JSON object #1284

Closed
azaroth42 opened this Issue Oct 9, 2017 · 8 comments

Comments

Projects
None yet
7 participants
@azaroth42
Copy link
Member

azaroth42 commented Oct 9, 2017

Reviewing the situations when we use URIs as strings rather than as the id of a resource encoded as a JSON object, I propose the following design pattern:

If a URI could be treated as a value in an enumerated list, such that the context could assign a short form to it, then the URI MUST be given as a string. Conversely, if this is not the case and the number of resources is either unbounded or impossible to enumerate, it MUST be given in the object form with at least an id and type. All enumerations defined by IIIF specifications MUST be encoded in the respective context as easy-to-remember-and-use strings.

There are a countable number of renderingHints, renderingDirections, choiceHints, timeModes, profiles, features, and types, which must thus all be strings. There is an uncountable number of logos, licenses, thumbnails, canvases, images, etc. which thus must be given as objects.

@workergnome

This comment has been minimized.

Copy link

workergnome commented Oct 9, 2017

I agree with this proposal—it makes a good distinction. Does this effect the guidance given around community extensions provided by additional contexts, in that they might be full URIs or short forms?

@tomcrane

This comment has been minimized.

Copy link
Contributor

tomcrane commented Oct 11, 2017

👍

1 similar comment
@jpstroop

This comment has been minimized.

Copy link
Member

jpstroop commented Oct 11, 2017

👍

@zimeon

This comment has been minimized.

Copy link
Member

zimeon commented Oct 11, 2017

👍

To @workergnome 's point, I think that stuffing an extension URI into a field where a string is expected ends up being OK. An unaware client might interpret the URI as a string, but it would be unique and unsupported, and so ignored.

Minor mathy technical comment: the set of all URIs is countable, so the difference is between a small number of renderingHint, renderingDirection etc, and a large number of logo, license, etc. ;-)

@mikeapp

This comment has been minimized.

Copy link
Member

mikeapp commented Oct 12, 2017

👍

@azaroth42

This comment has been minimized.

Copy link
Member Author

azaroth42 commented Feb 9, 2018

To move forwards on this issue ... it's more fine grained than the current design patterns.

I propose a new section 3 to the patterns document that describes the JSON(-LD) design patterns we've adopted.

@azaroth42

This comment has been minimized.

Copy link
Member Author

azaroth42 commented Mar 21, 2018

Change to consider towards #1479 fix is that we want to allow widely used / well known URIs defined by other specifications to be used directly without defining an alias for them in the context. This results in arrays with both short strings and URIs, but that's okay ... the viewer just needs to process the URI as a string.

Proposed change to the last sentence of the middle paragraph (the actual text):

All enumerated values defined by IIIF specifications or the appropriate IIIF extension registry MUST be encoded in the respective context as easy-to-remember-and-use strings. Externally defined URIs MAY be used directly.

@jrochkind

This comment has been minimized.

Copy link

jrochkind commented Oct 1, 2018

For those less familiar with json-ld, can you give an example of what a "object form with at least an id and type" might look like for a previous example which, if I understand correctly, previously would have been simply free text string?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.