Spec questions & suggestions

[toxi]

Hi Jamie & everyone,

I just heard about this project again due to the recent Obama playa
release and its use of my library, so I thought I'd take a closer look
at the spec again to see if it has drastically changed since the 1st
release. Whilst there're comments in the XML, some key points still
seem to be a bit obscure/not clear to me and so it'd be great to get
some clarification on those. Please don't take my prodding below as
anything but constructive criticism! I'd just like to get a better
understanding of your thinking behind some of the current syntax
constructs and wonder if they couldn't be improved/made more clear...
One of the benefits of XML based formats is legibility for both
machines & humans and semantics should be clear/self-documenting...

<Client> node:

1) What is the role and use case(s) for the data stored in the
<client> node? In my imagination, I'd understand a client to be a
consumer of GML data (e.g. the Obama playa) and if this is so, why
would we need to store its IP, geoloc etc.? The semantics of those
bits in the example documents seem to more indicate the actual
authorship info and references to the tool used to generate the GML,
no?

2) What is the difference between the <permalink> & <uniqueKey> nodes?
A permalink URL is by definition a unique identifier, why need the
other? And what format is the uniqueKey supposed to take? It certainly
doesn't look like GUID (http://en.wikipedia.org/wiki/GUID) or URI -
using the latter would be much preferable, especially if your aiming
at the linked data web...

3) Why are keywords comma separated and not specified as multiple
<keyword> nodes, which would allow parsing them into a list structure
directly and generating the XML from a database easier too?

4) What scope is the <username> value supposed to be valid under? Why
not use the artist's home URL, email address (or SHA1 of the email for
privacy reasons)? E.g. See FOAF for inspiration:
http://xmlns.com/foaf/spec/#term_mbox_sha1sum - Is GML designed to
have a direct dependency on 000000book.com?

5) I'm aware it's easiest to express times in openFrameworks as *nix
timestamp, but I would still propose to rather change this to a more
human friendly format, just as in Atom/RSS formats. My vote would go
to ISO 8601 which comes in different levels of precision, supports
timezones and seems to provide a good compromise between ease of human
& machine parsing... E.g. 20100909T23:14:00Z - http://en.wikipedia.org/wiki/ISO_8601

<Environment> node:

1) Which of the 2 nodes refers to the tag's centroid: <offset> or
<origin>? Here I'd propose to also include (or replace one of them
with) a bounding rect/box node (in normalized coords) so that tags can
be easier scaled & transformed around their bounding rect's centroid.

2) What is the value range of offset/origin? Normalized or screen
space coords?

3) What is the value range of rotations? Degrees or radians?

<Drawing> node:

1) Why is the <brush> considered a child of the <stroke> node if you
imply (via the <spec> node) that brush descriptions are top level
objects (like tags) and will at some point be able to be loaded from a
URL. Since you already have a <tag> top level node (currently slightly
obsolete, see other comment below), it'd make sense to consider moving
<brush> definitions to the same top level and keep the one within
<stroke> to just reference one of those global brushes & override
already set parameters for just that stroke.

2) Why is the <layerAbsolute>/<layerRelative> a property of a brush
and not of a <stroke> directly? It's the strokes which are/can be
layered, no?

3) Again, IMHO the <uniqueID> & <spec> values are semantic duplicates
and I'd refactor the current <uniqueStyleID> node into a URI value
with an option name attribute.

4) Since all other values (coords, vectors) are normalized, why not
keep the colors like this too? Would make it more OpenGL compatible
too... You could also offer a "hex" attribute for 6-digit RGB values
as optional alternative...

<Tag> node:

All GML documents I've seen so far only contain a single tag, so why
have this superfluous <tag> childnode, if <gml> already is your root
node? The <tag> would only make sense if you plan on introducing other
top level elements and/or distributing several tags within one
document (which would break REST principles). Also, for actually being
truly valid XML you should include the <?xml version="1.0"?>
processing instruction as first line...

Last, but not least...

Maybe some of these mentioned slight changes to the overall XML syntax
would make this format a bit friendlier and more flexible/extensible/
future proof. For existing documents the changes to an updated syntax
could be easily automated using a simple XSLT batch process...

Again, I hope these comments are valid & not seen as grating. I'd be +
+grateful for some answers & happy to help with things if needed!

Best, K.