Subject: [core] Attribute names in link-format

From: Zach Shelby <[email-masked]>
Date: Wed, 2 Feb 2011 13:13:25 +0200

I am satisfied with the tickets we have in for link-format as a result of WGLC, however one thing still bothers me. 

People have been confused about the use of n= and d= from their assumed names, and I think a small adjustment could make them more logical. 

Resource name (n=) is often confused with a human readable title (which title= is meant for).  On the other hand Interface Description (d=) is often confused with what n= is meant to be used for, because they associate d= with description rather than interface.

To clean that up I propose the following small change in the names of these attributes (the actual content of them is OK).

Resource name (n=)  ---->  Resource description (d=)

Interface description (d=) -----> Interface description (if=)  

Comments?
Zach

-- 
Zach Shelby, Chief Nerd, Sensinode Ltd.
http://zachshelby.org  - My blog "On the Internet of Things"
http://6lowpan.net - My book "6LoWPAN: The Wireless Embedded Internet"
Mobile: +358 40 7796297

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 2 Feb 2011 13:00:34 +0100

> Resource name (n=)  ---->  Resource description (d=)

Minor point:
I probably wouldn't reuse a name that already got some implementation/testing, unless there is a good reason.

I'm still not quite sure I understand the old n=, so I don't know what to suggest instead of d=.
It appears to be an application-specific or general semantic name for the *class*/*type*/*kind* of the resource.
So it's like the interface description, except less interfacy (verb-oriented -- what can I do) and more semanticy (noun-oriented -- what does it mean).  In my brain, there is still a significant overlap.

Gruesse, Carsten

---

From: <[email-masked]>
Date: Wed, 2 Feb 2011 12:07:01 +0000

reassigning the meaning of d= is just bad. Use longer, clearer, attribute names.

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On 
> Behalf Of Zach Shelby
> Sent: 02 February 2011 11:13
> To: core WG
> Subject: [core] Attribute names in link-format
> 
> I am satisfied with the tickets we have in for link-format as 
> a result of WGLC, however one thing still bothers me. 
> 
> People have been confused about the use of n= and d= from 
> their assumed names, and I think a small adjustment could 
> make them more logical. 
> 
> Resource name (n=) is often confused with a human readable 
> title (which title= is meant for).  On the other hand 
> Interface Description (d=) is often confused with what n= is 
> meant to be used for, because they associate d= with 
> description rather than interface.
> 
> To clean that up I propose the following small change in the 
> names of these attributes (the actual content of them is OK).
>

---

From: Zach Shelby <[email-masked]>
Date: Wed, 2 Feb 2011 14:12:53 +0200

> I probably wouldn't reuse a name that already got some implementation/testing, unless there is a good reason.

Good point, no good reason other that that description makes some sense.

> It appears to be an application-specific or general semantic name for the *class*/*type*/*kind* of the resource.

Correct, this is the purpose. Possibly "Resource type (t=)" could be a more appropriate name for this attribute. I am happy to add some more text clarifying it better.

> So it's like the interface description, except less interfacy (verb-oriented -- what can I do) and more semanticy (noun-oriented -- what does it mean).  

That is a good analogy. The Resource type is the noun (what does it mean). Whereas the interface description is really just mechanical, what can I do with this REST interface.  

> In my brain, there is still a significant overlap.

The only overlap is that you can sometimes deduct the types of resources that use a particular interface. For example you may define an interface description for all Sensors. Which described how you can GET the sensor's value. You still need a Resource type to tell you something useful about what kind of sensor resource that is. In other cases the interface description might be very generic, maybe just telling you that the interface lets you GET a value, which is returned as e.g. EXI.

So you really need the combination of both Resource type and Interface description to make an interface both mechanically and semantically useful. 
Currently it is assumed that each application space, system or deployment will define its own interface descriptions and resource types. However some future work in CoRE could be to define some really generic ones for general use if people would find that useful. Already building automation has started in that direction.

Zach

---

From: Zach Shelby <[email-masked]>
Date: Wed, 2 Feb 2011 14:16:10 +0200

> reassigning the meaning of d= is just bad. Use longer, clearer, attribute names.

I know. Resource type (rt=) would also work for example.

The WG seems to prefer 2-3 letter abbreviations for efficiency sake.