search

uber-hypermedia / specification

UBER Hypermedia Specification
http://uberhypermedia.org
24 stars 5 forks source link

Description field for the data element #2

Closed inadarei closed 9 years ago

inadarei commented 9 years ago

From @inadarei on August 3, 2014 23:45

In real-life forms fields typically aren't just title/value pairs, but frequently also contain "description" field, to provide context, explanation or hints in addition to the typically very short "title" field. I think "data" could use it as well.

It may be often empty, but when you need it, you could really use it

Consider this example:

{ 
        "name"    : "Profile Photo Upload",
        "rel"     : ["http://api.example.com/rels/profile-photo"],
        "url"     : "http://api.example.com/profile-photo",
        "action"  : "replace",
        "sending" : "multipart/form-data",
        "model"   : "{?user-id,photo}",
        "data"    : 
        [
          {
            "name"  : "user-id",
            "value"   : "User ID"
          },
          {
            "name"         : "photo",
            "value"          : "Profile Photo",
            "description"  : "Please provide PNG files with at least 300dpi resolution" 
           }
         ]
      }

Copied from original issue: mamund/media-types#45

inadarei commented 9 years ago

Description field can be equally useful for representing a response data-set, allowing server to provide hints for labels to be used for each field.

Example:

      { 
        "name"  : "firstname",
        "description"  : "First Name",
        "value" : "Joe" 
      },
      { 
        "name"  : "middlename",
        "description"  : "Middle Name",
        "value" : "Frank" 
      },
      { 
        "name"  : "lastname",
        "description"  : "Last Name",
        "value" : "Smith" 
      },
      { 
        "name"  : "email",
        "description"  : "E-mail",
        "value" : "joe.smith@example.com" 
      }
inadarei commented 9 years ago

From @mamund on August 4, 2014 18:20

i can see the value here. how would this look in the XML flavor? an attribute? a unique child property? a DATA element w/ a special attribute marking it as a description?

​

inadarei commented 9 years ago

From @graste on August 5, 2014 20:1

As the current spec looks like, description should probably be an attribute. That would suffice for many use cases like description="should be >= 2 kb" while description="should be <= 1024 kb" needs to be escaped. Descriptions that contain some sort of markup or are multiline are a bit weird as attribute though and would be nicer as a node with CDATA value. Nonetheless that would be the easy solution.

I'm wondering though if the now simple format should stay like that. At the moment the node value is the value and thus it's hard to do e.g. a description in a locale other than the whole resource's language. Moving things from attributes to nodes has some advantages in my opinion, but is more verbose:

...
<data name="todo" rel="item http://example.org/rels/todo" url="http://example.org/list/2">
    <data name="title" locale="en_US">Paint the fence</data>
    <data name="dueDate" type="date">2014-06-01</data>
</data>
<data name="todo" rel="item http://example.org/rels/todo" url="http://example.org/list/2">
    <data>
        <title locale="en_US">Paint the fence</title>
        <name>dueDate</name>
        <type>date</type>
        <value>2014-06-01</value>
    </data>
    <data name="someString">
        <value xml:space="preserve" literalize="false">  false   </value>
    </data>
    <data name="itemDone">
        <value literalize="true">false</value>
    </data>
</data>

The space attribute is from the whitespace handling section of XML. The literalize attribute could be custom or in the spec to allow literalization of e.g. boolean values to give hints of whether the string or the boolean value true is meant. This adds lots of complexity for XML and JSON though. I'd be happy if it would just be allowed to enhance Uber with custom attributes or nodes. Something like allowing any custom attributes on data elements via XSD: <xs:anyAttribute namespace="##any" processContents="lax" />.

inadarei commented 9 years ago

From @mamund on August 6, 2014 18:56

yeah, this is definitely a challenge to the XML model.

i think it still makes sense to express it as an <data> element.

why not just have name="description"? why do we need to add an attribute here?

​

inadarei commented 9 years ago

Thanks Mike, Steffen,

couple things I like about expressing description as a <data> element:

  1. Keeps uniformity of the approach. Is more extensible design.
  2. In XML using <data> and putting description in the value of the data element means ability to use CDATA and therefore not worry about reserved characters, which are expected to show up in a field like "description".

On the flip side, using the data element is more verbose, but then again: it's XML so... :)

I do think, however, that if we use a data element we need to have proper qualifier for the data element, unambiguously signaling to the client: "this is description, yo!". I think "name" is a wrong field to do that because then we will have to reserve certain words in "name" as having special meaning and I don't think that was the intention of the name field.

We also shouldn't use "rel", because rels are really for links and using rel when you have no link feels bad. Maybe we need to have a "class" attribute, for qualifying non-link elements as having special meaning.

Following are examples of each implementation, to compare and contrast:

Using attribute:

<data name    = "Profile Photo Upload" 
      rel     =  "http://api.example.com/rels/profile-photo"
      url     = "http://api.example.com/profile-photo"
      sending = "multipart/form-data"
      model   = "{?user-id,photo}"
      description = "A standalone system that manages profiles &amp; avatars"
      >

  <data name        = "user-id"
        description = "Please provide PNG files with at least 300dpi resolution"
     >Profile Photo</data>
  </data>

</data>

Using a "data" element and "class" qualifier attribute:

<data name    = "Profile Photo Upload" 
      rel     =  "http://api.example.com/rels/profile-photo"
      url     = "http://api.example.com/profile-photo"
      sending = "multipart/form-data"
      model   = "{?user-id,photo}"
      >
  <data class="description"><![CDATA[A standalone system that manages profiles & avatars]]></data>
  <data name= "user-id"        
     >Profile Photo
    <data class="description">Please provide PNG files with at least 300dpi resolution</data>
  </data>
  </data>
</data>
inadarei commented 9 years ago

From @mamund on August 6, 2014 21:49

yeah, name="description" is a bad idea -- good point.

the notion of class makes sense. this is a way to add more semantic information to data elements (not transitions) besides id and name. transition elements have rel for this, right?

maybe we should just use rel on data elements for this? maybe change the name from rel to class and use that for transitions?

inadarei commented 9 years ago

I personally like "rel" and "class" being separate. Link relations have well-established meaning and I am not for extending that meaning since that can easily create confusion. Similarly renaming "rel" to "class" also feels bad for familiarity.

inadarei commented 9 years ago

From @mamund on August 7, 2014 2:12

@inadarei:

so, do we agree that the rel and class provide the same "semantic annotation" service? IOW, rel allows us to add semantic annotation to <data> elements that have the href attribute and class allows us to add semantic annotation to <data> elements that do not have the href attribute.

does that sound right?

inadarei commented 9 years ago

That sounds great to me!

inadarei commented 9 years ago

From @mamund on August 7, 2014 5:6

if that's right, why not use the same attribute name in both cases? is there a name that makes sense for both? optimized for machine parsing, not only human mental parsing?

inadarei commented 9 years ago

LOL I should know better to foresee that when Mike agrees with me, he's secretly setting a trap :) Well played, sir.

To answer the question, "rel" has well-established prior meaning and both ways of using single attribute feel to me like we would violate backwards compatibility with that prior meaning:

  1. If rel starts to mean 'both link relations and non-link semantic annotation' - we are changing processing rules for an existing thing.
  2. If we start using "class" and stop using "rel", we have removed something that existed before.
inadarei commented 9 years ago

From @mamund on August 7, 2014 7:28

I should know better to foresee that when Mike agrees with me, he's secretly setting a trap :)

ROFL! you have uncovered my modus operandi ;)

srsly, tho. one of the design aesthetics in UBER is to strip away conventions and focus on the heart of what is needed for H-Factor expressions in a message model. so i think it is good to notice similarities and not shy away from the notion of distilling this into the model.

as for "changing the processing rules..." i don't follow this. which rules are changed where in UBER? and, even if they are, is that bad?

and what do you mean by "...we have removed something that existed before"? existing where? before what?

UBER still an incredibly young idea. it is not a stable spec and at this stage changing the characters R-E-L to C-L-A-S-S (or any other value) is not out-of-bounds if it results in a better design.

inadarei commented 9 years ago

I consider "rel" attribute to be well-established way of marking link relations specifically. And then deriving all the rest of my convictions, which I expressed above, from there.

That said, I hear you about 'sometimes you break conventions' so I will stop sounding like a broken record and let others chime-in and you decide in the end.

FWIW, if you decide that it is a good idea to go with one attribute, my preference would be: "rel". Expanding the meaning of "rel" to non-links sounds better than expressing link relations with "class". At least to me.

inadarei commented 9 years ago

From @mamund on August 7, 2014 14:21

so, to follow up on the "well-established way..." of rel, there can be a downside to that. the "purist" view of the rel attribute is that is SHOULD NOT ever indicate and action and SHOULD ONLY indicated a relationship. i've had some gnarly convos w/ HTML wonks on this.

it might be good to NOT use rel since it a) allows ppl some additional freedom in picking values that are not strictly relations, and b) breaks out of the mold of HTML-rel 'think'

maybe?

inadarei commented 9 years ago

From @mamund on August 23, 2014 22:23

what about using the attribute called "semantics" on any DATA element?

this would replace @rel and be a valid property whether the DATA element had a URL property or not.

On Thu, Aug 7, 2014 at 3:32 AM, Irakli Nadareishvili < notifications@github.com> wrote:

I consider "rel" attribute to be well-established way of marking link relations specifically. That said, I hear you about 'sometimes you break conventions' so I will stop sounding like a broken record and let others chime-in and you decide in the end.

FWIW, if you decide that it is a good idea to go with one attribute, my preference would be: "rel". Expanding the meaning of "rel" to non-links sounds better than expressing link relations with "class". At least to me.

— Reply to this email directly or view it on GitHub https://github.com/mamund/media-types/issues/45#issuecomment-51440085.

inadarei commented 9 years ago

I think I prefer the attribute name "role"? Shorter and less "intimidating" than "semantics", imho. Possibly slightly more abstract too.

mamund commented 9 years ago

@inadarei

on this description attribute -- all cool for me.

i assume this is about decorating data elements that are primarily values, but not sure.

your two examples:

are very diff, BTW. one is for something in addition to a label (the first). the second is one as a label. i want to make sure we don't get confused on what we're doing or how we suggest this be used.

for the record, there are a handful of things in HTML-land that come close to this functionality:

we should be clear on what we're doing here -- our primary aim. i think our goal is to offer the ability to associate prompts w/ data (for both input and display) for humans. we already have id and name and rel which as all machines will need. the next thing we need to be sure of is if we are doing this for just value items (e.g. HTML.LABEL) or also for link items (e.g. HTML.A@title or HTML.IMG@alt, etc.)

if we want to support both we should pick a name and a general use-case that makes sense for both. and i'd like to avoid repeating my mistake w/ url and model -- i thought templating use would be mutually exclusive, but found out we wanted to template both properties in the same control.

that's my $0.02

inadarei commented 9 years ago

@mamund, I agree with you 100%. I think @description should be considered as part of larger support for more expressive forms.

What I am doing in my example No. 1 has issues. Specifically, this example:

{ 
  "name"    : "Profile Photo Upload",
  "rel"     : ["http://api.example.com/rels/profile-photo"],
  "url"     : "http://api.example.com/profile-photo",
  "action"  : "replace",
  "sending" : "multipart/form-data",
  "model"   : "{?user-id,photo}",
  "data"    : 
  [
    {
      "name"  : "user-id",
      "value"   : "User ID"
    },
    {
      "name"         : "photo",
      "value"          : "Profile Photo",
      "description"  : "Please provide PNG files with at least 300dpi resolution" 
     }
   ]
}

assumes that the inner data element "explains" the params of the model. But nowhere in UBER is that a normative representation of a behavior. In that specific API I was going to document the behavior in API-specific documentation. However, our appetite has increased since then, I think :)

While discussing other issues closed last week, we've discussed a possibility of standardizing fuller support for forms, including: how form params can be documented in the message response itself.

mamund commented 9 years ago

so, is this description item only about FORMS support? that's kinda what my Q was above.

let's make sure we agree on what we plan to be doing w/ description

FWIW, i think we have all we need for supporting FORMS for machines already. Maybe we need more features for humans, tho (e.g. labels for values, inputs, and links).

inadarei commented 9 years ago

Fixed: https://github.com/uber-hypermedia/specification/commit/98ef1ce75c9f62a80a1033b86164f46b0a426b6a