Open nicholascar opened 5 years ago
I have partially addressed all these concerns in Commit https://github.com/w3c/dxwg/commit/2843f9f11df2ae5f8e66444d09370967cdbba6fc. For each point:
It's going to take a little time to get this definitions point right as we have to redo the naming of Resource Descriptor
(Issue https://github.com/w3c/dxwg/issues/573) so I can't address all of these now but I have de-duplicated hasRole & hasResourceRole (the latter is redundant).
I have added in a definition for "aspect" straight from the dictionary: "a particular part or feature" and I think this make clear the generic usage of the term is intended. I have updated the definition for hasArtifact
to be the much clearer: "An rdfs:Resource that implements the Resource Descriptor". For "implementing resource object" I have updated the Usage Note to read: "A property to link from a :ResourceDescriptor to an actual resource (rdfs:Resource and an individual) that implements it".
All definitions use the same style ("A..." or "An...") except for one of the two coming directly, unaltered, from Dublin Core Terms: dct:standard
.
There has been much discussion about the name of the class and, as indicated above, discussion for this is now in Issue https://github.com/w3c/dxwg/issues/573 which is linked to in the doc. Also, I have changed the wording as you suggest to replace "must" with "allows for" or similar.
Where? I only see dcterms in the citation [[DCTERMS]], I can't find any other occurrences. There were 3 occurrences in the Roles vocab, now updated.
I've addressed the points you raised and many other points of spelling and grammar have now been addressed by a series of edits from Antoine, Karen, Lars, Andrea, Alejandra so I think this is in a much better state now.
From another email from Makx:
“how to negotiate for Internet resource content using profiles” – is the ‘internet resource’ here the data (e.g. dataset) that conforms to the profile?
“alignment of multiple specialised resources” – what are those?
“a more generic version of the requested resource, using a profile link to the thing it profiles” – is the ‘requested resource’ here the data (e.g. dataset)? What is the ‘profile link’ and what is the ‘thing’?\
“acceptable fallback options for resources when the primary requested profile is unavailable” – again, is the ‘resource’ here the data (e.g. dataset) that the client wants to access?
Responses, 7 - 10:
http://example.com/a/resource
, Content Type
conneg may allow you to get it as an HTML doc (Accept: text/html
) or other Media Types, conneg by profile will look like Accept-Profile: http://example.com/profile/x
for /a/resource dct:conformsTo
the profile http://example.com/profile/x
, if the server supports it.I'm not sure any changes to the Profile Ont doc are needed here though; this is for the Profile Conneg doc.
Resource Descriptor
class) then those constraints or other resources might also be aligned using the formalized profile relations.I think this opaqueness arises from the use of 'resource' here. I have altered the sentence to "this will assist with alignment of multiple specialized resources, such as constraints language files, within profile, and perhaps with reducing the total effort and information necessary to specify a profile". Does this shed any light?
If the Profile, :Profile_X
for example, that the resource claims conformance to is described using this ontology then it may say :Profile_X prof:isProfileOf :Standard_Y
. The server, being unable to deliver the requested resource in accordance with Profile_X
may, nevertheless, be able to deliver it according to the more generic :Standard_Y
and that may be of use to the client.
@makxdekkers: please let me know if, based on this explanation, more information should be added to the Profiles Ontology document.
Many thanks!
First of all, I think some of the confusion comes indeed from the term 'resource'. I would suggest defining two phrases very early on, use them consistently and not use the term 'resource' by itself: 'profile resource' : an artefact that implements a profile and is the object of the prof:hasArtifact property. 'data resource' : a dataset, document or any other object on the internet, excluding profile resources.
On specific points:
Issue 2. I still don't understand "aspect - a particular part or feature - of a Profile". In my mind, the ResourceDescriptor defines the profile, not just a part or feature of it. My suggestion for the definition would be: "a specification of the profile with a certain role in a certain format" or more generic (if the ResourceDescriptor is more loosely associated to the profile) "an object associated with the profile with a certain role and in a certain format".
Issue 3. Yes, many do start with "A(n)" but the information is not on the same level. For example, I would suggest to change (prof:token) "A property for identifying this Profile for use in APIs" to "A label or name for the described profile, for example to identify it for use in APIs" and to change (prof:isInheritedFrom) "A Profile's Resource Descriptor has been inherited from a Base Specification" to "A standard or profile from which the described profile re-uses rules and constraints". There are still properties that do not use the same style, e.g. prof:hasRole "Functional role of an Resource" which I suggest could be improved as "A purpose of the profile resource, e.g. whether it is to provide the specification, guidance or a machine-readable validation file". I have suggested many reformulations in the annotated PDF file I sent you yesterday.
Issue 5. My fault. I checked and all is OK.
Issue 7. My confusion was with the phrase "Internet resource". If I understand correctly it is the 'data resource' as defined at the beginning of this comment to which a profile is applied, delivering it in a certain way. It is confusing because the instantiation of the profile itself, the object of prof:hasArtifact, is also an "Internet resource" and a "HTTP resource"; the thing I suggest to call the 'profile resource'.
Issue 8. My issue is with "alignment", "specialized" and "resources". Alignment: what is that? The verb "to align" implies activity -- "to bring into line", but I don't see this here. Is it rather to express relationships instead of aligning? Specialized: do you mean something like 'domain-specific' or 'application-specific'? The term 'specialisation' is often used for sub-classing, with 'generalisation' used for super-classing, and I don’t think that’s the intended meaning here. Resource: that's indeed a big confusion -- are you using it here as a synonym for 'profile' or maybe 'profile resource' (defined as the object of the prof:hasArtifact)? In your new sentence, what are "resources ... within profile"?
Issue 9. You introduce 'generic HTTP resource', but I guess this is again what I suggest to call a 'data resource'. The issue itself was about the formulation of the sentence, which in my mind is not clear, because I don't understand "generic", "profile link" and "the thing it profiles". If I understand correctly, you're addressing a situation where a client asks for data resource according to a particular profile, but the server cannot deliver it that way and instead delivers the data resource according to some other profile that is somehow more 'generic' (do we have a definition of what makes one profile more generic than another?). I still don’t understand what “using a profile link to the thing it profiles” means.
Issue 10. Yes, it is the same issue but also a problem with the formulation. My suggestion would be something like: "A client may be able to generate a request that already indicates acceptable fall-back options (i.e. alternative profiles) for the delivery of the data resource in case it cannot be delivered conforming to the primary requested profile".
+1 to @makxdekkers suggestion to not use "resource" alone. Data resource and profile resource are better; ideal would be to not use resource at all, due to confusion with its meaning in RDF, but I can't think of another term that would work.
@kcoyle Maybe 'data object' and 'profile object' would work better?
+1 to using "x object"
Perhaps a 'profile object' is a good thing...
I don't think the editorial issues raised by @makxdekkers have been completely addressed, and we stumbled upon some of them also while preparing the ESWC paper.
I would suggest we add this to the work to be done for the 2PWD of PROF.
Assigning as "editorial" since "I don't think the editorial issues raised by @makxdekkers have been completely addressed"
@makxdekkers could you please check the candidate 3PWD (the ED at https://w3c.github.io/dxwg/prof/) and see if what I think is the main remaining issue here, that "...the confusion comes indeed from the term 'resource'..." is now resolved?
@nicholascar
My suggestion was:
I would suggest defining two phrases very early on, use them consistently and not use the term 'resource' by itself: 'profile resource' : an artefact that implements a profile and is the object of the prof:hasArtifact property. 'data resource' : a dataset, document or any other object on the internet, excluding profile resources.
In the current draft at https://w3c.github.io/dxwg/prof/, I see you have not followed my suggestion and still use the word 'resource' for several types of things. There is a definition of 'resource' at https://w3c.github.io/dxwg/prof/#definitions that says that the word is used to identify what I suggested to be called a 'data resource' but the document seems to use the word mostly to indicate what I suggested to be called a 'profile resource'. So, no, I don't think the confusion has been resolved.
I do have some issues with the Profiles Ontology at https://w3c.github.io/dxwg/profilesont/, mainly with the definitions.
several definitions are substitutions in the template "A [Domain] [property label] [Range]" (e.g. "A dct:Standard has a Profile") which is not really helpful, as it makes the definitions circular (e.g. hasProfile, hasResource, isProfileOf etc.). Others still use the same words: e.g. property hasRole "Functional role of an Resource"; hasResourceRole "The role that an Resource plays". Terms like "functional", "role" and "Resource" need to be explained. Actually, from the definitions of hasRole and hasResourceRole, it is not immediately clear what the difference is.
Other terms that should be explained are "aspect" (in the definition of Resource Descriptor), "artifact (resource)" (in the definition of hasArtifact) and "implementing resource object" (in the Usage Note for hasArtifact).
Not all definitions use the same style, e.g. some have "A ..", other have "The ...", still others do not start with an article, and the definition of hasToken starts with "A property for ...". This should be made consistent.
The usage note of Resource Descriptor (as I wrote in GitHub, I think this is a really bad name) puts constraints (using "must" twice) on the way it is to be implemented. It might be better to formulate this as suggestions rather than obligations, e.g. "the formalism used can be expressed using dct:format and any adherence to a dct:Standard can be expressed using dct:conformsTo to allow for machine mediation. For human understanding, its purpose can be expressed via a relation hasRole to a ResourceRole".
Dublin Core terms are sometimes given as dct: and sometimes as dcterms:.
The document needs a spelling/grammar check. There are broken sentences (e.g. "Base Specifications or Profiles can have Resource Descriptors associated with them that defines implementing rules for the it"), misspellings ("GeoDCAt", "RDf", "StatDTAC-AP", "available", "summarises") and singular/plural errors (A vocabulary .. are provided").
I tend towards voting -1 if those issues, in particular 1 and 2 above, are not addressed, as I think these issues make the document hard to understand for an outside audience. However, because I am late with my comments, I can vote -0 if people think these are all minor issues that can be repaired in 2PWD.