Re: [vwrap] informal description of the DSD interface description language

[Dzonatas Sol <[e-mail]>]

Some notes... in line...

Meadhbh Hamrick wrote:
> hey peeps, it shouldn't be shocking to anyone i'm not a big fan of 
> lentczner's "little" interface description language, llidl. while it 
> can be argued it's "condensed" format is easy enough to use, once 
> mastered, i prefer something mildly more expressive. when i was 
> working on the last version of the LLSD draft, i solicited comments 
> from several implementers inside and outside Linden, and they all said 
> the same thing: "LLIDL is cool enough, but it looks like line noise if 
> you don't know what you're looking at."
>
> i came up with the following interface description language to address 
> the "looks like line noise" critique. this is the IDL that's going in 
> the DSD draft, since that's what we're using at sl8.us <http://sl8.us> 
> and various sensor projects that are using DSD. i'm assuming you've 
> read and understand the LLIDL section of the most recent type system 
> draft.
>
> again, i have no idea if this will be relevant since no one's stepped 
> up to be an document author for future revisions of this group's docs 
> or an editor to re-draft a new charter. but on the off chance people 
> do this and still want to work on the type system, these are the 
> changes recommended by several LLIDL users and implementers.

Be sure to see review these to see how I based off LLIDL:
http://wiki.secondlife.com/wiki/User:Dzonatas_Sol/SNOW-375#Queries_.26_Type_System
http://wiki.secondlife.com/wiki/User:Dzonatas_Sol/SNOW-375_Resources/Asset
http://wiki.secondlife.com/wiki/User:Dzonatas_Sol/SNOW-375_Resources/Interface
(and others there)

Note that I used more of what is in regards to ReST than only LLIDL.

>
> *item 0 : disentangling resources from interfaces.*
>
> LLIDL sort of conflated a resource (something to be accessed) with the 
> method of accessing it. there was no way to "officially" define a 
> "resource" independent of the semantics to access it. DSD says that 
> RESOURCEs are just data definitions. INTERFACEs define how they're used.

As I see "resource", it manly is untranslated to any particalar 
implementation. Some still think there is an obvious implementation due 
to common resources being used by HTTP. I think you have some like C#'s 
interface in mind?


>
> *item 1 : say good-bye to the di-graphs.*
>
> several people noted that LLIDL, at first glance, looks like line 
> noise. this is because of the use of digraphs to represent messaging 
> semantics. cast your memory back to the LLIDL resource description for 
> the seed cap:
>
>     %% seed
>       -> { capabilities: [ string, ... ] }
>       <- { capabilities: { $: uri } }
>
>
> the '%%' digraph means 'start of resource description'. the '->' means 
> 'this is what i'm going to send you' and the '<-' digraph means 'i 
> expect you to send me this back'.
>
> instead of digraphs, the DSD resource description language uses the 
> keyword "RESOURCE" to begin a resource. it also terminates the 
> resource definition with a semi colon. so a resource declaration would 
> look something like this:
>
> RESOURCE <resource name> [resource definition] ;
>
> resource DEFINITIONs look more or less like they used to. for example, 
> here's a RESOURCE definition for a typical error response:
>
>     # Resource description for a typical error resource
>     RESOURCE error_simple {
>        success     : false,    # clients check the success element to
>     see if there was an error
>        errno       : integer,  # this is a numeric code representing
>     the error
>        error       : string,   # this is a text description of the error
>        description : uri       # this is a URL that points to a HTML
>     web page describing the error
>     };
>

Think we discussed this before, which I said wasn't much of the worry 
since the what is pivotal is more significant. That said, however, be 
sure to keep in mind that anything like digraphs make it easier to use 
non-English only keywords.

We seem to agree in structure.



>
> *item 2 : the use of type literals instead of type names*
>
> in the example above, we used 'false' instead of 'boolean' as the type 
> definition for the 'success' element of the error resource. DSD 
> resource definitions can use type literals to imply that the element 
> should exist, and should have a specific value. so if you wanted to 
> define a resource that represented the origin of a 3d space, you could 
> use:
>
>     # Point in a 3D rectangular space 
>     RESOURCE cartesian_point [
>        real,  # x coordinate
>        real,  # y coordinate
>        real   # z coordinate
>     ];
>
>     # Origin of a rectangular (cartesian) space
>     RESOURCE cartesian_origin [ 0.0, 0.0, 0.0 ];
>

Good idea, I'm just not quite sure if it is so obvious in practice.


>
> *item 3 : type specifiers use the same names as the elements inside 
> the XML serialization.*
>
> instead of using "int", we use "integer." ditto for other types. so 
> the resource definition. here's a resource definition for something 
> with an integer in it:
>
>     # Random resource definition of a map with an integer in it
>     RESOURCE whatever {
>        element : integer
>     };
>

This is made obvious by the default use of LLSD, still. Notice SNOW-375 
I did have a few extras for optional fields and proprietary fields. We 
know they are there, but probably won't have an public definition of 
such structures. Guess we need that tidbit formalized.


>
> *item 4 : DSD variant declarations don't suck for beginners*
>
> i always thought repeated '&' definitions to denote variants was sort 
> of snobbish. it makes sense to peeps who've sat through classes on 
> regular grammars and ABNF, but i wouldn't mind it too much if someone 
> with a basic understanding of procedural coding could understand what 
> was going on. so i came up with the VARIANT keyword. it looks like this:
>
> VARIANT <variant-name> : <variant-type> { <variants> }
>
> so here's an example:
>
> # Enhanced Error resource
>
>     RESOURCE error_enhanced VARIANT error_type : string {
>         'number' : {
>           success : false,
>           errno : integer
>        },
>        'string' : {
>           success : false,
>           error : string
>        },
>        'url' : {
>           success : false,
>           description : uri
>        }
>     };
>
>
> what this means is that the "error_enhanced" resource has three valid 
> forms, that look like:
>
>     RESOURCE error_enhanced {
>        error_type : 'number',
>        success : false,
>        errno : integer
>     };
>
>     RESOURCE error_enhanced {
>        error_type : 'string',
>        success : false,
>        error : string
>     }
>
>     RESOURCE error_enhanced {
>        error_type : 'url',
>        success : false,
>        description : uri
>     }
>
>
> so the <variant name> shows up as an element in each of the valid 
> forms as an literal element of type <variant-type>.

Did I find any significant use for such? I mean is there somewhere in 
specific that that variant structure is more helpful than what I used? I 
think as we get into more specific usage and documentation of that usage 
we do need simplified ways makes some redundancy obvious. I just used 
wiki markup for that for now, I think.


>
> *item 5 : say good by to HTTP verbs.*
>
> LLIDL as specified is pretty much intertwined with HTTP. many people 
> thought that was a bad idea. In creating an interface, DSD uses five 
> abstract "interaction semantics": CREATE, READ, UPDATE, DELETE and EVENT.
>
> the first four do what you expect them to do while the last one 
> describes the form or "shape" of an unsolicited message coming from 
> the event queue.
>
> so if you wanted to login, you might use the following interface
>
>     INTERFACE CREATE session_factory {
>        username : string,
>        secret : binary
>     } RESPONSE VARIANT success : boolean {
>        false : {
>           errno : integer,
>           err : string,
>           description : uri
>        },
>        true : {
>           seed : uri
>        }
>     };
>
>
> or, you could do the following:
>
>     RESOURCE error {
>        errno : integer,
>        err : string,
>        description : uri
>     };
>
>     INTERFACE CREATE session_factory {
>        username : string,
>        secret : binary
>     } RESPONSE VARIANT success : boolean {
>        false : error,
>        true : {
>           seed : uri
>        }
>     };
>
>
> so anyway, i'm writing up this stuff in the DSD type system draft. 
> feel free to comment. as things stand, if VWRAP continues as a working 
> group, i'll integrate your comments on the draft. if not, i'll modify 
> the draft so as to remain compatibility with existing DSD 
> implementations and publish it a an individual / informational draft 
> for the purpose of registering the mime types.
As long as usage doesn't fall out of ReST than it'll work. Remember that 
ReST doesn't have to use HTTP. If you see my implementation, there is 
the ReST queue being full of tasks and part of those task relate to HTTP 
methods. People don't seem to often split ReST queries as different than 
HTTP verbs, but I do. I guess that is like resource/interface differences.

I thought I saw another submitted document to review, yet couldn't find 
it. Was there a newer version?



-- 
--- https://twitter.com/Dzonatas_Sol ---
Web Development, Software Engineering, Virtual Reality, Consultant