New Draft comments: Specific Resources

Hi,

While the discussion on literal vs resource bodies continues, I've decided to go for a break ;-) and check the rest of the documentation before the January 28 deadline.
Here are some comments for the Specific Resource module,
http://www.openannotation.org/spec/future/specific.html
as of January 20.

I think most are editorial, though some may touch on slightly deeper issues...

Best,

Antoine

====

1. Positioning of Rendering
Does Rendering really fit a section on Specific Resources? States and Selectors are about restricting the "extent" of a resource being annotated. But Styles seem quite different beasts. This is in fact quite explicit in Fig 3.1.1 that positions "Specific Resource before styling. Bar comment 11, there's also the quite puzzling fact that oa:styledBy is attached to an Annotation resource, not to a specific body or target.
So I'd suggest to move Styles in their own module. *Or* to label the module as "Specifiers". Indeed, for a reason that I'm entirely grasping, "specifiers" include more than what is needed to produce Specific Resources; that could have a nice effect of fitting better the entire module as it is defined now.


2. Figure 3.1.1 and specifiers workflow.
Fig 3.1.1 and many sentences in the text around it (e.g., "then a Selector describes", "this chain") hint that there is a mandatory flow of state-selector-style. As mentioned before, Styles are on a quite different level. And besides, there is nothing that requires a State to be applied in addition to a Selector, or the other way around. Applying a State can lead straight to the SR node in the graph of Fig 3.1.1. And a Selector can be applied straight to a resource in the "Source" box. In fact one can read a contradiction between Fig 3.1.1 and "the complete image is the Source" in the text: because what the text says is a Source, would be in fact a Representation in Fig 3.1.1.
Finally, Fig 3.1.1 does not state anything about Scopes.
I think the idea is to express that States must be processed before Selectors etc, and this is valuable. But there are perhaps way to render it in a way that is less prescriptive of what should happen, and how the ins and outs of every step are to be refered to.


3. Specific Resource Class.
As it stands, I'm wondering whether this class is needed at all. After all, one doesn't need the type, it is more the properties like oa:hasSource or oa:hasSelector that are important here. Unless SpecificResource is needed as a kind of functional "slot" which could be used in serializations where such slots have to be provided (as in plain XML)?
In all case, the sentence "The oa:SpecificResource class SHOULD be associated with a Specific Resource." needs more motivation: what happens if someone doesn't use this type?


4. Fig 3.1.2
In the text that introduces there should be a reminder on why the node spTarget1 is a non-resolvable resource (I suppose a pointer on the discussion on fragment URIS could help).
The label of the node "target1" is quite confusing, as this node is supposed to be a Source.


5. Selector class
Same question as in #3 (and as for other types of specifiers; but I'll stop at this one): is this class needed? I see that it's not used in Fig. 3.2.


6. Resolvability of Selectors, States, etc.
Unless I'm overlooking something, I feel that not enough is said on why these resources are described as having non-resolvable URIs in the example graphs.


7. Query in 3.2: "a resource" -> "any resource"


8. Fragment Selectors vs. Range Selectors
It seems there is overlap between some Range Selectors and some Fragment ones. For example, I suppose that Fragment Selectors using RFC5147 will be equivalent to a family of Text position selectors.
I know that OA needs both types, and the specification of every equivalence is certainly out of scope. Yet a reader may be puzzled about which one they have to choose of several practically equivalent alternatives. And data consumers may be harmed down the stream, if a same thing can have two representations.


9. Text normalization
3.2.2.1 (Text Position selectors) says the text should be normalized before counting characters. Fine, but:
- is it a SHOULD?
- if yes, could there be a link that tells implementers what kind of normalization it is?


10. Fig 3.3.2
A specific header request would be really helpful, instead of "headers1".


11. Levels of Style properties
I'm certainly missing an explanation somewhere, but at this point it's still not very clear to me from the text, why oa:styledBy is attached to the Annotation resource, while oa:styleClass is attached to a specific resource.
It seems to me that having all predicates associated with specific resources would make more sense. It would also fit better the whole idea of Specifiers that belong to the body or the target level.


12. Levels of Scopes
The current proposal where oa:hasScope is attached to specific resources makes much sense. Cases where there are multiple specific resources and/or scopes involved in an annotation come to mind...
But the text falls quite short on explaining this. Instead, it includes expressions that could lead to confusion, such "It is sometimes important for an Annotation to capture the context in which it was made" and "As such scoping information is only true for a particular Annotation". Granted, there's not wrong, it's just that they can be misleading for readers.


13. Body/target vs. Specific resource, re-loaded
3.5 features the sentence: "it must be attached to a Specific Resource, and not to the Body or Target directly." while Fig 3.5 has (as flagged earlier) a node labeled "target1" as the Source. This is very confusing, because of course it is spTarget1 that is the object of oa:hasTarget.
Following comment 4, I'd recommend to replace target1 by source1 in Fig.3.5 and replace the problematic sentence by
"it must be attached to a Specific Resource (Body or Target), and not to the Source directly."
and then update the rest of 3.5.
I suppose there are a couple of places in the Module where such re-wording has to be done.

Received on Sunday, 20 January 2013 21:12:02 UTC