[vwrap] informal description of the DSD interface description language

[Meadhbh Hamrick <[e-mail]>]

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 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.

*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.

*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
};


*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 ];


*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
};


*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>.

*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.

-cheers
-meadhbh
--
meadhbh hamrick * it's pronounced "maeve"
@OhMeadhbh * http://meadhbh.org/ * [e-mail]