questions about cj spec

54 views
Skip to first unread message

Ricardo Kirkner

unread,
Feb 23, 2014, 10:20:26 AM2/23/14
to collect...@googlegroups.com
Hi,

I was looking for a cj client/parser library for python, and since I couldn't find any, I started my own (this is also a good way to learn about the format).
I've implemented the basics already, but I still have to rough some edges before this can be useful. From reading the spec there are a few places where I'm not sure how to interpret it.


1. href property of collection object

    "The collection object SHOULD have an href property. [...]"

this means the href property can be excluded under certain circumstances

    "[...]This URI SHOULD represent the address used to retrieve a representation of the document. [...]"

this means if provided it should be a URL

What happens if the href is not provided? Is it to be included in the representation? Does it have a default value? This applies to the href property of 'items' too. Is the following a valid representation of a collection+json document?

{
  "collection": {}
}


2. SHOULD vs REQUIRED

    "[...]Each object is MAY have any of three possible properties: name (REQUIRED), value (OPTIONAL), and prompt (OPTIONAL)."

the use of MAY indicates that each property is optional, however 'name' is identified as required; which one is it?


3. rel and name properties

I think it's natural to expect a rel value to be duplicated; that is multiple links can have the same rel value. However, is it possible for two or more links or queries to have the same name property?


thanks
Ricardo

mca

unread,
Feb 23, 2014, 10:35:51 AM2/23/14
to collect...@googlegroups.com
Ricardo:

great to see your post here and always good to see people writing clients for Cj. ;)

as to your Qs...

1) "...What happens if the href is not provided? Is it to be included in the representation? Does it have a default value? This applies to the href property of 'items' too."
- i include the element (link, query, item) with a default href of the current URL (href={self}). This is usually *Not* what authors intend (they usually just _forgot_ the href) but it is a way to continue to execute at runtime w/o throwing fatal errors.

"Is the following a valid representation of a collection+json document?

{
  "collection": {}
}"

docs say this is a minimal valid representation: http://amundsen.com/media-types/collection/examples/#ex-minimal

but the above is accepted by my parser by filling in the missing "version" as "1.0" and the missing href as the current URL of the request. Again, my goal is to not throw any fatal errors at runtime.

2) "...the use of MAY indicates that each property is optional, however 'name' is identified as required; which one is it?"
yeah, bad spec writing there. "name" is REQUIRED for "data" elements. if it is missing I currently leave the data element out of the rendering. I considered generating a random unique value for "name", but rejected that idea. open to other thoughts.

3) "is it possible for two or more links or queries to have the same name property?"
yes, it is possible and this would still be a valid document from the Cj POV. This is especially helpful for "data" elements but counter-intuitive for "link" and "query" elements. I haven't run into any runtime problems with it tho and have left this alone. open to other thoughts here, too.

please keep us posted on your progress.

Cheers.




--
You received this message because you are subscribed to the Google Groups "Collection+JSON" group.
To unsubscribe from this group and stop receiving emails from it, send an email to collectionjso...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

Ricardo Kirkner

unread,
Feb 23, 2014, 10:51:59 AM2/23/14
to collect...@googlegroups.com
Hi Mike,

thanks for the reply


On Sun, Feb 23, 2014 at 12:35 PM, mca <m...@amundsen.com> wrote:
Ricardo:

great to see your post here and always good to see people writing clients for Cj. ;)

as to your Qs...

1) "...What happens if the href is not provided? Is it to be included in the representation? Does it have a default value? This applies to the href property of 'items' too."
- i include the element (link, query, item) with a default href of the current URL (href={self}). This is usually *Not* what authors intend (they usually just _forgot_ the href) but it is a way to continue to execute at runtime w/o throwing fatal errors.

"Is the following a valid representation of a collection+json document?

{
  "collection": {}
}"

docs say this is a minimal valid representation: http://amundsen.com/media-types/collection/examples/#ex-minimal

but the above is accepted by my parser by filling in the missing "version" as "1.0" and the missing href as the current URL of the request. Again, my goal is to not throw any fatal errors at runtime.


so, while the document received might not be valid (it's missing the href value), your client generates an equivalent document that is valid by specifying the href value as the current url. My question was more aimed at the case of a document validator. If I hand over a document to a cj validator, and that document doesn't have an href, what should the validator say? (of course, in real world scenarios, your client can cope with malformed documents in certain cases, as you explained)

 
2) "...the use of MAY indicates that each property is optional, however 'name' is identified as required; which one is it?"
yeah, bad spec writing there. "name" is REQUIRED for "data" elements. if it is missing I currently leave the data element out of the rendering. I considered generating a random unique value for "name", but rejected that idea. open to other thoughts.

+1 to following the REQUIRED/OPTIONAL hints, it's just the MAY word that made me doubt
 

3) "is it possible for two or more links or queries to have the same name property?"
yes, it is possible and this would still be a valid document from the Cj POV. This is especially helpful for "data" elements but counter-intuitive for "link" and "query" elements. I haven't run into any runtime problems with it tho and have left this alone. open to other thoughts here, too.

thanks
 

please keep us posted on your progress.

I will, thanks

mca

unread,
Feb 23, 2014, 10:53:55 AM2/23/14
to collect...@googlegroups.com
"My question was more aimed at the case of a document validator."

aha!

yes, then i'd throw an alert as a validator if the "version" and "href" were missing in the minimal response.

actually, have not worked up a validator for Cj. that is a very good idea!





Ricardo Kirkner

unread,
Feb 23, 2014, 11:07:42 AM2/23/14
to collect...@googlegroups.com
great! I'll include that then, thanks!

mca

unread,
Feb 23, 2014, 11:08:58 AM2/23/14
to collect...@googlegroups.com
cool.



Ricardo Kirkner

unread,
Feb 24, 2014, 7:10:01 PM2/24/14
to collect...@googlegroups.com
Hi,

just wanted to share the initial version of this library.

https://github.com/ricardokirkner/collection-json.python

This is quite plain right now but I intend to add features to it to make the most common use cases easy.
I hope you find it useful, or at least an interesting read. In any case I welcome all kinds of feedback.

Ricardo

Will Clardy

unread,
Nov 5, 2015, 11:48:35 AM11/5/15
to Collection+JSON
Mike,

Regarding the possibility of two links with the same name property:
 
3) "is it possible for two or more links or queries to have the same name property?"
yes, it is possible and this would still be a valid document from the Cj POV. This is especially helpful for "data" elements but counter-intuitive for "link" and "query" elements. I haven't run into any runtime problems with it tho and have left this alone. open to other thoughts here, too.

It seems natural to me that some cases would warrant the use of multiple links with the same name property (consider a book with multiple authors, each author being a unique resource). Is there a more idiomatic means of expressing this type of relationship? Thanks!

mca

unread,
Nov 5, 2015, 1:01:48 PM11/5/15
to collect...@googlegroups.com
Will:

what you MAY want to do is mark a set of queries or links as being in the same "group" (author, collection, archive, shakespeare, etc). 

for that, the @rel value is useful. you can even mark the same link with multiple values in the @rel property (rel:"collection shakespear archive"). then client applications "looking" for all the shakespear links will find them easily.

the "name" is usually reserved for a value the client app can look for to fulfill a usecase ("where is the link for search?" "is the a query that returns the outstanding orders?", etc.).

however, Cj has nothing to say on this other than to offer possibilities that authors/service-providers can use in the manner they wish.

does this help?



mca
Mike Amundsen
For more options, visit https://groups.google.com/d/optout.

Will Clardy

unread,
Nov 5, 2015, 11:39:12 PM11/5/15
to Collection+JSON
Mike,

Thanks for taking the time to reply! Your answer does help to clear up the semantics of the rel and name properties. Your answer here regarding the appropriation of name for usecase hints is helpful. The following is the only mention I find of the semantics of the name property in the spec:

Each item in a Collection+JSON collection has an assigned URI (via the href property) and an optional array of one or more data elements along with an optional array of one or more link elements. Both arrays support a name property for each object in the collection in order to decorate these elements with domain-specific semantic information (e.g. "data" : [{"name" : "first-name", ...},...]).

I believe that I'm correct in understanding the spec as placing name in the realm of application-semantics. In that case, is the "usecase hinting" you described a convention, or am I missing something in the spec? Thank you for your help!

mca

unread,
Nov 6, 2015, 9:18:28 AM11/6/15
to collect...@googlegroups.com
<snip>
I believe that I'm correct in understanding the spec as placing name in the realm of application-semantics. In that case, is the "usecase hinting" you described a convention, or am I missing something in the spec?
</snip>
first, as I mentioned, in the last msg. "Cj has nothing to say on this other than to offer possibilities that authors/service-providers can use in the manner they wish."

IOW, the use of name & rel is open for authors/providers for whatever they wish.

second, as to the "application-semantics" space, that is correct - name/rel are for application-level work. they are not need for protocol-semantics (HTTP/XMPP, etc.) or for message-level semantics (Cj, HTML, UBER, etc.).

cheers
 



Reply all
Reply to author
Forward
0 new messages