add optional "title" element to collection object

[mamund]

add the optional title element to the collection object. this can be used to present human-friendly titles in UI displays.

{"collection" : {
  "version" : "1.0",
  "href" : "http://example.org/list/",
  "title" : "A Simple List",
  "links" : [...],
  "items" : [...],
  "queries" : [...]
  }
}

this can be ignored and the change is backward compatible.

[carlesjove]

I'm not a big fan of introducing UI related properties on CJ. I think prompt is great because it's a kind of inline documentation, but a title property looks more like passing a variable to a view than actually documenting what the collection is about…

[mamund]

@carlesjove

i understand your POV. i think there are many ways to use Cj and i'd like to make sure it is not difficult for some folks. i know as i work out several examples of generic clients, this is a major helper value.

keep in mind this is optional too, not even a SHOULD, just a MAY.

would you feel different if we said that prompt could be an optional property of collection?

[carlesjove]

My concern is: if a title property is included (even if it's called prompt), where do we stop? I guess that title is expected to be the page/section title to be rendered in a view, but a view is likely to have more than just a title and a list of items. So, would it make sense to add a subtitle, or maybe a body too?

I'm just thinking loud, and I don't really have a strong opinion on this, but what if instead of a title object, a more general one like view, content or copy was introduced, and this is where all view oriented content would go? As I said, it's just something I'm thinking as I write, but maybe it'd be more future proof in the sense that all copy would be stuffed in one object/array.

[mamund]

@carlesjove

i understand your concern. just because it is possible that we could add too many collection level properties doesn't mean it is probable. of course "too many" is a vague term anyway and i don't want to get into attempts to quantify that, either ;)

i will also say that i am not a fan of adding a new aggregation block (object or array) at the collection level, but i'm open to your ideas on this. i certainly don't want to start a new block with just one property (title) and i am not at all interested in moving some existing properties (e.g. version and/or href) in order to justify creating a new collection level block. let me know what you have in mind here and we can discuss.

finally, apart from the fear of an explosion of properties at the collection level, it sounds like you don't have a problem with the concept of an optional title and the primary concern here is about the long-term sustainability of the Cj design itself. if that is true, then we are in high agreement here and just need to find a reasonable way to include the ability to offer a string for the visual display of information about the current representation. feel free to take this as an oppty to come up with some alternate ways to solve the problem at hand.

[carlesjove]

What about a contents (or similar) object that takes a data array? Thus, naming is left open and anyone can use what they need:

// Someone might want regular names
"contents": {
  "data": [
    {"name" : "title", "value" : "Posts", "prompt": ""},
    {"name": "body",  "value": "All Posts written by our staff. Blah blah blah", "prompt": ""}
  ]
}

// Someone might want CSS hierarchy
"contents": {
  "data": [
    {"name" : "header > h1", "value" : "Posts", "prompt": ""},
    {"name": "main > p:first-child",  "value": "All Posts written by our staff. Blah blah blah", "prompt": ""}
  ]
}

I'm looking at this situation also from the perspective of someone who's trying to support Cj on the backend. Most Ruby libraries I'm working with have a generalist DSL to be re-used by other media types. New top-level properties are a bit harder to add support to, because they may need specific DSL methods, so that's why I'd keep them to a minimum.

[mamund]

@carlesjove

what i think you're proposing is a new collection level array block that is essentially a property bag. something that holds a set of loosely-typed values that can be added by anyone for any purpose.

i can see the value here:

• this is a one-time change to the model that supports lots of unknown futures
• it offers the possibility of simplifying support for existing server-side generator tooling

i can also see some problems:

• nothing added here will be "first class" properties and that means we can NEVER use MUST in specifying any thing that goes here.
• actually using them on the client-side is more tedious (bixeling through the collection) and it will be impossible to create generic clients that depend on anything in this collection.
• in order to put any constraints (or assurances) on names and values in this collection, we'd need to create a new registry of valid values similar to the IANA rel values registry.

finally, while i understand the challenges of implementing libraries for media types, i don't want to allow the limitations of some programming languages or frameworks to over-constratin the design of the message. it's a balance, tho.

certainly, adding title to the collection object is no more onerous than adding a new metadata block to the same collection object. the question is does it make sense to do just one of these options.

[carlesjove]

@mamund

I see what you mean by problems… I was really thinking of how an organization might want to pass a random number of contents for views and layouts, but it is true that this makes it almost impossible for a generic client to process. I guess I was looking at the situation from the wrong perspective.

Forget about the contents aggregator.