Subject: [link-relations] NEW RELATION: form

From: Ioseb Dzmanashvili <[email-masked]>
Date: Tue, 10 Apr 2012 23:25:03 +0400

Dear All,

I've submitted new draft of the 'form' link relation type:http://datatracker.ietf.org/submit/status/40699/b546af566ca2a9264b9f7d36582d9bdb/

Description:
- The link relation is intentionally generic, and it can be used with  multiple media types in a wide variety of use cases.

- When included in a resource which represents a collection, the 'form'  link relation identifies a target resource that represents the form for adding a new member to the context collection.
- When included in a resource which represents a member of a collection, the 'form' link relation identifies a target resource that represents a pre-populated form for editing the context resource.

Could you please review?
Thanks in advance!

Best regards,
Ioseb

-- 
Ioseb Dzmanashvili
Lead Architect
Picktek LLC
24b Khazbegi ave. 
Tbilisi, 0177, Georgia
T (+995 32) 39.58.56, F (+1 202) 315.3934
picktek.com
code.ge
github.com/ioseb
twitter.com/iosebi

---

From: Bjartur Thorlacius <[email-masked]>
Date: Tue, 10 Apr 2012 19:45:26 +0000

On 4/10/12, Ioseb Dzmanashvili <[email-masked]> wrote:
> - When included in a resource which represents a collection, the 'form'
> link relation identifies a target resource that represents the form for
> adding a new member to the context collection.
> - When included in a resource which represents a member of a collection, the
> 'form' link relation identifies a target resource that represents a
> pre-populated form for editing the context resource.
>
What about hierarchical collections, collections of collections? Than
member collections would be both members and collections making this
relation ambiguous.

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Wed, 11 Apr 2012 00:12:37 +0400

Hi Bjartur,

Thanks for response!

> member collections would be both members and collections making this

Good question, though I do not think it's a problem. It depends where you
put the link. Same question will be relevant to the *edit* relation, though
it depends where you put it.

For example, if I have collection which contains other collections, it
doesn't necessarily mean that top level collection is directly writable and
it's reasonable to put *form* links inside sub collections and this will
mean "add new item/entry to the collection". On another hand, if sub
collections contain entries, putting *form* link on entry level will mean
"edit this particular entry".

If there is some extremely complicated hierarchy of collections it's
questionable whether this thing is writable/editable on it's own rights
IMHO. It's very easy to create complicated structures with XML/JSON though
it doesn't mean that whole hierarchy is manageable through single form.

Again, in my opinion it completely depends on design and intent.

Best regards,
Ioseb

---

From: Bjartur Thorlacius <[email-masked]>
Date: Tue, 10 Apr 2012 20:44:36 +0000

> "edit this particular entry".
So, if the context represents a collection, the target is instructions
(a form) for adding a member to the collection, and if not, it's
synonymus with the edit link relation?

First of all, modifying resources is so common that it should be
standardized as much as is practical. Firstly, it must be possible to
link to more alterable representations of the resource. Secondly,
modified versions must be redistributable. The latter is usually
realized by sending the modified version to whomever served the
original.

The alterable version may be in a specialized format improbably
already understood by the user agent, but that shouldn't be too much
of an issue if it has an unique media type. Then the server may accept
modified versions using a standard protocol.

But none of that has much to do with collections. I propose a more
specific link relation: add or append.

The new link relation would have the semantics you described of a form
for adding a new member to a collection, but not a form for modifying
a resource.

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Wed, 11 Apr 2012 01:19:34 +0400

> synonymus with the edit link relation?

Exactly. Though with one difference, it doesn't necessarily mean that creation *form* and edit *form* are exactly same i.e. edit form MAY have different structure depending on purpose of a resource.

> realized by sending the modified version to whomever served the

I'm not sure I understand what you mean here. How it can be possible in all cases for all media types to just modify representation and send it back? Does it imply that all kinds of representations in all cases contain sufficient amount of information which give flexibility to agents to just modify and send back to owner? 

> modified versions using a standard protocol.

First of all not all representations of resources are self contained enough and doesn't give agents enough information regarding data types of particular attributes of the resource.

> But none of that has much to do with collections. I propose a more specific link relation: add or append.

"add" or "append" what? property? image? video? It's a way confusing compared to very generic *form* which is way clear and well understood by everyone IMHO.

> The new link relation would have the semantics you described of a form for adding a new member to a collection, but not a form for modifying a resource.
*form* doesn't lack this semantics.

ioseb

---

From: Bjartur Thorlacius <[email-masked]>
Date: Tue, 10 Apr 2012 21:57:29 +0000

On 4/10/12, Ioseb Dzmanashvili <[email-masked]> wrote:
> I'm not sure I understand what you mean here. How it can be possible in all
> cases for all media types to just modify representation and send it back?
That's most certainly not guaranteed. Some resources are pracrically
immutable, for example. And "sending back" is often not possible; in
which case users typically share or forward.

> Does it imply that all kinds of representations in all cases contain
> sufficient amount of information which give flexibility to agents to just
> modify and send back to owner?
>
Nope. The owner may not care at all for modifications of
representations. But we should have some way to link to more alterable
representations. A wiki might for example wish to provide both HTML
representation of documents and their wikitext source. An application
might want to serve both compact JavaScripts and, say, verbose Java
sources they were translated from. Same with raster graphics and
vector sources, etc.

> First of all not all representations of resources are self contained enough
> and doesn't give agents enough information regarding data types of
> particular attributes of the resource.
>
That can be solved either by supplying a schema containing said
information, or by providing an alterable version of the resource.

> "add" or "append" what? property? image? video? It's a way confusing
> compared to very generic *form* which is way clear and well understood by
> everyone IMHO.
>
Search form? Comment form?
Given access to an incomprehensive collection of funny videos of cats,
an user might want to add a video to the collection, yes.
Note that we already have the relation *search* for search forms.

>> The new link relation would have the semantics you described of a form for
>> adding a new member to a collection, but not a form for modifying a
>> resource.
No, but *form* confusingly has two definitions; it has different
semantics depending on context. As one of the definitions is
equivalent to the definition of the registered link relation *edit*,
it would be simpler to narrow *form* to a single definition.

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Wed, 11 Apr 2012 02:42:55 +0400

> information, or by providing an alterable version of the resource.

That's why I propose *form* relation. Defining the link:
<link href="..." rel="form" type="[SPECIFIC_MEDIA_TYPE_HERE]" /> 
on the resource MAY refer to the *form* resource based on HTML5's rich form elements OR xforms OR some extended variation of Collection+JSON *template*, this will imply schema, it avoids statically defined schema and fulfill all other needs.

> Search form? Comment form?

- Search form is for building templated queries and has nothing to do with sending data to the server with POST/PUT/PATCH methods. 
- Comment form is most likely will be defined under /comments collection and collection purpose itself will strengthen the exact meaning of write *form*.

> an user might want to add a video to the collection, yes.

Yes but this definitely means that there is a collection of videos and video + it's additional attributes can be happily POSTed to the collection. 

One thing that worries me in this discussion is that *context* and *media types* are not respected. In my opinion these arguments are relevant to some very custom handcrafted(not even proprietary media types) "representations" of applicatoin/xml and application/json types rather than properly designed media types. If this is the case both applicatoin/xml and application/json lack any hypermedia abilities by default and it's very easy to mess up. 

> Note that we already have the relation *search* for search forms.

Again this has nothing to do with *write* forms. *search* is a query not a write request.

> it would be simpler to narrow *form* to a single definition.

I do not agree. First of all *edit* as defined by AtomPub has triple meaning: fetch/modify/delete. And in AtomPub's case most likely it refers to the same *entry* as regular read link, and structure of the representation is same. Important factor here is support of DELETE method which refers to the same resource as well.

In case of *form* a) there is no restriction of the URI of the form; and b) semantics I propose imply that form SHOULD contain comprehensive information describing resource + contain values, and this in most cases imply that *read* representation and pre-populated *edit* form representation will be different and this is the key here. 

ioseb 

On Wednesday, April 11, 2012 at 1:57 AM, Bjartur Thorlacius wrote:

> On 4/10/12, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Thu, 12 Apr 2012 20:15:34 +0400

Hello everyone, 

Any feedback? 

Thanks!

Best regards,
Ioseb