Definitions of Specific Resources: Example

[gsergiu]

In my opinion the example for specific resources is inconsistent with the introduction text in the
https://www.w3.org/TR/annotation-model/#specific-resources and with the WA Principles
https://www.w3.org/TR/annotation-model/#web-annotation-principles

Concretely, The introduction text says:
While it is possible using only the constructions in the core data model described above to create Annotations that reference parts of resources by using Fragment URIs, there are many situations when THIS IS NOT SUFFICIENT. For example, even a simple circular REGION of an image, or a diagonal line across it, are NOT POSSIBLE.
.......
For example, if the Target of the Annotation is a circular region of an image, then the SpecificResource is the circular region, it is described by a SELECTOR, and is also associated with the source Image resource.

1. The first issue I see is that the selector is not representend in the example .. as stated in the text above:
   {
   "@id": "http://example.org/anno12",
   "@type": "Annotation",
   "body": {"@id": "http://example.org/comment1"},
   "target": {
   "@id": "http://example.org/region1",
   "@type": "SpecificResource",
   "source": "http://example.org/image1"
   }
   }
2. According to the text in the WA Principles I would expect that one of the specific constraints must be present in the representation of Specific Resources:
   -- The resource with these constraints is a separate resource from the Annotation, Body or Target, and is called a SpecificResource.
   -- The SpecificResource refers to the source resource and the constraints that make it more specific.

According to my understanding one of the following contraints must be present, otherwise is not a specific resource but a regular resource. Am I right?

The types of additional specificity that are available:
-- State: Describe the desired representation of the source resource for the Annotation
-- Selector: Describe the desired segment of the source resource for the Annotation
-- Style: Describe the style in which the source resource should be presented for the Annotation
-- Scope: Describe the scope in which the source resource applies for the Annotation
-- Role: Describe the role that the source resource plays for the Annotation

[gsergiu]

see also related ticket: #139

[azaroth42]

Agree that this is an issue. The editorial issue is that by the time we get to just Section 4. (e.g. where the example is) we haven't introduced any of the specifiers (State, Selector, etc.) so it seems weird to have them in the example.

I suggest the easiest and least confusing correction is to remove the example and the use case, but to leave the basic model components. Then have a note that functionally complete examples are in the sub-sections below. Would that satisfy the concern, @gsergiu?

[gsergiu]

That is an option.
My main concern here was the understanding of the text.
If I understood correctly, than one of the specific attributes: State, Selector, Style, Scope, Role is mandatory for SpecifcResources.
If that is the case, I would recommend to make this mroe explicit in the text. Even if that will be in the form of a "(Development) Note".

Maybe it is not a bad idea to add also a "role" (purpose) to the example. In this case it would be ok to have "role" and "selector" in the example as the next two sections explain these properties.

We can introduce references to the related sections in the introductory text. For me the following text looks like an summary of the section 4 ... (and I would place references on the State, Selector, Style, Scope, Role).

The types of additional specificity that are available:

State: Describe the desired representation of the source resource for the Annotation
Selector: Describe the desired segment of the source resource for the Annotation
Style: Describe the style in which the source resource should be presented for the Annotation
Scope: Describe the scope in which the source resource applies for the Annotation
Role: Describe the role that the source resource plays for the Annotation

Sounds this like a good solution?

[azaroth42]

Fixed: http://w3c.github.io/web-annotation/model/wd2/#specific-resources

[gsergiu]

Hi Rob,

Mybe I'm to picky, but I would like ot ask why is the purpose a property of SpecificResources only and not any regular external resources? With regard to this I discovered a set of inconsitencies:

1. The definition of the purpose is outdated now, as it doesn't includes the posibility to use it in the SpecificResources

http://w3c.github.io/web-annotation/model/wd2/#motivation-and-purpose

purpose Relationship    The relationship between a TextualBody and a Motivation.
There MAY be 0 or more purposes for each TextualBody.

1. There is contradiction between the definition of the purpose as shown above, and the definition of the purpose in the SpecificResource

   The types of additional specificity that are defined by this document:
   Purpose: Describe the purpose of including the source resource in the Annotation
   

   Is purpose relationship between Resource (including here the TextualBody) and the Annotation, or the Motivation? I think that consistency is required.

2. I have a question about the modeling of Bodies. It seems at least for now as the Body is a Resource. However, I think that in the real world, the body includes a resource (which has own properties as url, language, mime-type, propably also a label or title) and other metadata describing actually the sope and role of the body within the context of the Annotation (basically ... all what the motivation is not able to say about the body ... like purpose, selector, scope, etc.).

So ... my suggestion would be se separate these concerns, otherwise they will get more and more confusing...

I would suggest to consider the following representation for bodies:

body : {
resource:{
@id : myurl.com,
language : en,
mime-type: text/html,
title/label: mywebpage
},
@type: TextualBody/ExternalResourceBody/SpecificResourceBody,
purpose: roleOfBody
selector: {...}
.....
}

Of course ther can be the minified representation
body: myurl.com
equivalent for
body : {
resorce:{ @id: myurl.com}
}

... body .. should have no @id as the body should be serialized only whitin the annotation.

BR,
Sergiu

[gsergiu]

PS: as explanation of the point 3.
I think it is mandatory to separate the metadata describing the resource from the metadata which is actually related to the expected intepretation and behaviour. see also #113 #11

[azaroth42]

Commenting with new proposals on a closed issue isn't a great way to ensure attention. Please raise new issues, one proposal per issue.

To comment on the 3 points, however....

1 & 2: The description of purpose as it relates to TextualBody could be better. I'll duplicate the description from the SpecificResource definition.

3: That's what a Specific Resource is.

[gsergiu]

1&2 Well .. there is the principle in softare development, that the tester should not be the same person as the developer. It is common that fixing isues have side effects, in which case the isues are set back to "not fixed" status. I don't have the power to do this, but maybe you have it... if you find that my reports/arguments are correct. (Creating a new issues on the same topic is not the recommended way to handle such situations)

with regard to 3. I agree that is what the class SpecificResourse is ... only that the name of the class is missleading.
This class is the class of the body and not of the web resource. The body is not the resource.

You will probalby not agree with that but there are arguments already written in the current version of the draft:
a) External Web Reource: @id Bodies or Targets which are External Web Resources MUST have exactly 1 id with the value of the resource's URI.

Specific Reource: id A Specific Resource MAY have exactly 1 URI that identifies it.

I think that there is the contradiction in these definitions, the Specific class cannot restrict the "definition" from the Generic class. So ... external web resources must have an id and consequently, Anything that may not have an @id is not a Web Resource!

b) All examples in the SpecificResources don't have an @id and consequently none of them is a (Web)Resource ! (they are simply sub-properties of the Annotation which is a web resource as it has an @id)

c) I think I complained about this before, but the definition of the SpecificResource class doesn't really makes sense:

SpecificRerouce: The class for Specific Resources
The SpecificResource class SHOULD be associated with a Specific Resource

Of course that a SpecificResource is a class of a Specific Resource.... however it is not clear at all ... id the Specific Resource can be a Target, A Body or an ExternalWebResource? ...

d) source: ```
The relationship between a Specific Resource and the resource that it is a more specific representation of.
There MUST be exactly 1 source relationship associated with a Specific Resource. The source resource MAY be described in detail as in the core data model or be just the resource's URI.

 As I said before ... the Specific Resource is not a web resource as it doesn't have an id, it is only a "view" of a part of a web resource (which actually is embedded in the annotation)

e) If the SpecificResources are WebResources, why don't they have a language and format ... as defined in the core model of the WebResource? The correct answer is .. because they are not WebResources!

PS: I appologize if I'm harsh again ... but I know it is not easy to convince people at this stage, that Targets and Bodies have relations to Web Resources, but they are not web resources. This mistake comes from the minified version where 
body: "mywebsite.com"
should be interpreted as 
body:{ resource: {@id: "mywebsite.com"}}
and not as body:{@id: "mywebsite.com#title"}

... as the later could be in fact a minimized version of the following
body:{
@id: "mywebsite.com#title",
resource:{@id:"mywebsite.com"}
selector:{ 
type: "FragmentSelector",
value:"The title of my website"
}

}