Re: API issues for discussion

Hi all,

On 03/01/2011 11:13 AM, Bailer, Werner wrote:
> Dear all,
>
> As you know Florian with me on updating the API document based on the
> conclusions from the F2F. There are many things to do, and we hope to
> have a draft with most of the changes implemented before the telco
> next week.
>
> We also came across some issues which need discussion in the group:
>
> 1. Subtypes The subtype argument in getMediaProperty (used to filter
> the results) refers to different attributes depending on the
> property, e.g. type, role. This is a similar problem as in the
> previous API draft, where MediaAnnotion .type and .value represented
> different things depending on the property. We see two possible
> solutions:
> a) replace this argument with a pair (attribute,filterValue)
> b) keep subtype, but define for each of the return type interfaces,
> which of the attributes is mapped to subtype (if any)

although I am also concerned about the lack of regularity introduced by 
that "subtype" argument, I'm afraid solution (a) would be significantly 
harder to implement, for a benefit which is not certain.

So I would rather vote for solution (b); note that calling the argument 
"subproperty" would make it sound more generic...

Just a thought about that: we recently removed the 
getPropertyNamesHavingValues method, arguing that the filtering could be 
done by the programmer, as the number of values would never be very 
high... Wouldn't that argument apply to "subtype" as well?

> 2. Subtype link/label One conclusion at the F2F was to split
> attributes into link and label, depending on whether they are URIs or
> free text. This applies in many cases to type, role, etc. attributes
> of a property. When using subtype to filter the results of
> getMediaProperty, what does the filter value apply to? - specify
> whether it applies to link or label (this needs the approach proposed
> in 1a) - apply to both link and label and form the union of the
> results (assuming that we typically get matches only in link or label
> but not in both)

This issue, in my opinion, pleads for removing the "subtype" argument...

If we are to keep it, though, I would again vote for simplicity and let 
"subtype" (or "subproperty") match *either* the xLink or the xLabel 
attribute. If there is a real need to distinguish them, version 1.1 of 
the API will introduce "subpropertyLink" and "subpropertyLabel", and may 
even deprecate "subproperty".

> 3. Normative JSON We decided at the F2F to include in the API
> document a normative representation in JSON. The question is how to
> define this. - There is JSON Schema [1], which is probably the most
> precise way of doing it. However, I'm not sure whether it is useful
> to add this (given that there is already the WebIDL) and confuses
> readers more than it helps. - A complete set of examples (all
> attributes for all properties, might become lenghty). - A complete
> MediaAnnotation example, and examples for each of the properties
> containing the specific attributes.

I don't know how widely accepeted JSON-schema is in the JS community, 
but from my external perspective, it looks like a good solution.

Agreed: it may seem redundant with WebIDL and confusing, but if we 
insist on JSON being an *implementation* of the WebIDL definitions, it 
should not be too bad. And after all, all the JS examples use an 
implicit mapping from WebIDL to JS(ON), so we should as well make it 
explicit.

   pa

> Best regards, Werner
>
> [1] http://json-schema.org/
>
> -----------------------------------------------------------------------
>
>
>
>
Werner Bailer
> Audiovisual Media Group
>
> DIGITAL - Institute of Information and Communication Technologies
>
> JOANNEUM RESEARCH Forschungsgesellschaft mbH Steyrergasse 17, A-8010
>  Graz, AUSTRIA
>
> phone:  +43-316-876-1218            personal fax: +43-316-876-91218
> mobile: +43-699-1876-1218            general fax: +43-316-876-1191
> web:    http://www.joanneum.at/digital e-mail:
> mailto:werner.bailer@joanneum.at
> -----------------------------------------------------------------------
>
>
>
>
>
>

Received on Wednesday, 9 March 2011 10:16:55 UTC