Dxwg: Suggested updates to definition of PROF constructs

[aisaac]

@nicholascar @rob-metalinkage As discussed in our last PROF call, here are suggestions for updating the definitions and notes of some PROF constructs. For now I've focused on the ones of section 8.3 Class: Profile as this takes time, and I want to see how you react to my first suggestions before continuing this :-)

• prof:Profile still uses the old definition for profile, at odds with the WG definition (which is present in the PROF spec). The definition should be the official one, verbatim. I can live with keeping the note _"This definition includes [...]"_ in the definition, but it could also live a better life as a new scope note or usage note, in order to keep the "core" definition clean.

• prof:hasResource. The current definition (_"A resource which describes the nature of an artifact and the role it plays in relation to a profile"_) doesn't work very well imo. The resource doesn't describe by itself - that's the job of a document about the resource - rather, the resource is used as the subject of statements that describe the artefact. So I suggest to replace the definition by _"Relates a Profile to an artefact that implements (some aspects of) it, fulfilling a specific role in relation to the Profile."_

• prof:isProfileOf. The current definition (_"The subject of 'is profile of' defines constraints on the object which playes the role of a base specification"_) has a typo and is not well aligned with the new definition of profile (as it focuses on constraint). The style is also at odds with the other definitions (well, at least the one I'm leaning towards ;-) ). I suggest _"Relates a Profile to another data specification that it constrains, extends, combines, or provides guidance or explanation about the usage of"_.
  The usage note should also be refreshed. I suggest _"A Profile may be a profile of one or more specifications. This property is optional, allowing any specification to be declared at the root of a profile hierarchy."_ .This removes the bit on inheritance, which is probably better in other section(s) that discuss the semantics of profile hierarchies. Considering how the notion of inheritance is controversial in the WG, it's better to lower the number of times it appears in the document. The suggested note also gets rid of unnecessary/debatable detail (I don't think using the Profile class is necessary for the root for a profile hierarchy; anyway what's crucial for defining the root is to be a dead-end of a prof:profileOf chain, not to be of a given type...)

• prof:isTransitiveProfileOf. The current definition (_"A specification for which this Profile defines constraints, possibly through a chain of isProfileOf relationships"_) needs to be refreshed too: it focuses too much on constraints. In addition, we could put the technical aspect first, so as to highlight that this property is especially for convenience. I suggest _"The transitive closure of the prof:isProfileOf property. Relates a profile to another specification that it is a profile of, possibly via a chain of intermediate profiles that are in prof:isProfileOf relationships"_.
  I also suggest to amend the existing usage note, relinquishing it from too strong wording on conformance, into _"This is a convenience property that may be used to access all specifications (including other profiles) that could provide useful information and related resources for the Profile (for example, for better identifying conformance requirements). This avoids forcing clients to traverse a profile hierarchy to find all relevant resources. If this property is used, then all such relationships should be present so a client can safely avoid hierarchy traversal."_

• prof:hasToken The current definition and usage note are a bit confusing wrt the notions of "prefered" and "alternative" (that is a strict dichotomy in many contexts, for example in SKOS, where can't be such thing as a 'prefered alternative' label) and do not reflect well the suggestions made in #453 . In fact considering how the "token" aspect of the notion is key, I suggest to merge definition and most of the usage note, which were short anyway, into _"Relates the Profile to a identifier that can be used as prefered alternative to its URI, in circumstances where this URI cannot be used, for example in API arguments or in content negotiation."_
  The usage note could focus on the "simple" aspect of the token: _"The token shall be a simple lexical form of identifier that needs to be compatible with its circumstances of use, such as in API arguments or content negotiation."_
  In addition we could also change the main label of the property, into _"has prefered token"_
  Hopefully this caters for most if not all the comments made in last stages of #453.

[kcoyle]

isProfileOf: @aisaac suggests

"Relates a Profile to another data specification that it constrains, extends, combines, or provides guidance or explanation about the usage of"

I'd drop "another" and I am searching for a substitute for "relates" because that is a weak term. It's really making a statement about a relationship (and I cannot exactly express why relationship is a stronger term, but in my English-strict mind, it is).

"Defines the relationship of a Profile to a data specification that it constrains, extends, combines, or provides guidance or explanation about the usage of"

"Establishes the relationship of a Profile to a data specification that it constrains, extends, combines, or provides guidance or explanation about the usage of"

"States the relationship of a Profile to a data specification that it constrains, extends, combines, or provides guidance or explanation about the usage of"

[kcoyle]

hasResource

"Relates a Profile to an artefact that implements (some aspects of) it, fulfilling a specific role in relation to the Profile."

The object of this is an instance of the class ResourceDescriptor, which then contains a link to the resource. So I think this needs to read:

"Relates a Profile to the description of the resource that has a specific role in the Profile."

It can't have a role in "relation to" the profile, since the profile is essentially an abstract class. The various profile resources ARE the profile.

Again, I find "relates" to be weak, and think this could even be:

"The resource that has a specific role in the Profile."

This follows how DCAT has done its definitions, which essentially define the object of the property, not the property itself:

dct:conformsTo
Definition: | An established standard to which the described resource conforms.

I think this is clear as a definition model and greatly simplifies the definitions.

[kcoyle]

Using the DCAT definition model, isProfileOf becomes:

"a data specification that the profile constrains, extends, combines, or provides guidance or explanation about the usage of"

[makxdekkers]

@kcoyle
Which document are you looking at? In the editor's draft at https://w3c.github.io/dxwg/profilesont/, I see for hasResource: _A resource which describes the nature of an artifact and the role it plays in relation to a profile_, Your suggestion _The resource that has a specific role in the Profile_ (if we can change 'the' to 'a'), _A resource that has a specific role in the Profile_ sounds even better.
By the way, the definition of isProfileOf should be _A specification for which this Profile defines constraints_ to align with the definition of isTransitiveProfileOf.

[rob-metalinkage]

If you look at the conneg spec and the examples in the profile specification its quite clear that a "data profile" is a special type of profile.
Proposal:
a subclass of Profile called DataProfile which carries the "data profile" definition agreed and does not restrict the usefulness of the general model.

moved this issue to #1072

[rob-metalinkage]

@kcoyle making definitions terser is a good idea - but this example

dct:conformsTo
Definition: | An established standard to which the described resource conforms.

the defintion is actually about the object of the relationship "An established standard " and not about the relationship itself.
"identifies an established standard..." makes the definition about the relationship. Nevertheless is it possible to put concrete proposals in separate issues so we can vote on them - in general happy to accept most wording improvements but cannot process a multi-threaded issue.

[rob-metalinkage]

I have created a new specific issue around actioning the request to change the term "constraints"...

https://github.com/w3c/dxwg/issues/1070

Please move any discussion about that there - I think Karen's suggestions can be incorporated there.

I have also created and actionable issue #1071 to accept proposed changes to definition of prof:isTransitiveProfileOf

[kcoyle]

@makxdekkers I was working off of the definitions in Antoine's opening issue, which I assumed he had gotten from the document (but didn't check independently). If we're all working off of old defintions we should fix that ASAP.

[aisaac]

@rob-metalinkage I think for constraints we don't need to take into account IETF RFC 2119 yet. My suggestion is quite basic. It's only about consistency with the definition we agreed on. #1070 can be discussed later as it looks like it's about questioning again the agreed definition.
It's a bit the same for #1072 : whatever be our decision there, the next PWD needs to have the definition we've agreed on as main reference. (I've got further arguments but I'll put them in #1072)

@makxdekkers for hasResource @kcoyle started from my suggestion, which is indeed not the one in the current document.

[aisaac]

Another note that I opened this issue especially to handle misalignment between definitions and typos, I believe that we could leave the matter of harmonizing the 'style' open in 3PWD.

This said I think we should be careful about using the notion of "descriptions" in definitions in the position of "resource", as in "relates a Profile to the description of the resource that has a specific role in the Profile" or in "A resource which describes the nature of an artifact". Often descriptions are made by statements about resources, or document about resources, not by the resources we talk about, themselves.

[kcoyle]

@aisaac I'm not sure about your second paragraph, but PROF has "ResourceDescriptor" class as the object of "hasResource" not the resource itself. I've argued against this construction in ways that I read your comment to support, but the fact is that what "hasResource" links to is indeed a description. The actual resource is the object of "hasArtifact".

[aisaac]

@kcoyle let's try to DCATize or FRBRize a bit the elements in the definition _"A resource which describes the nature of an artifact and the role it plays in relation to a profile" ;-)
Roughly, the ResourceDescriptor is the resource that the artefact is a distribution/item of. This resource serves as an anchor for statements that relate to the artefact, but it's not a description itself. The same way as the resource of type prof:Profile is not really a description of the profile (rather, it represents the profile and is the subject of statements that together compose the description of the profile). I'm ok with the pattern, but I'm worried about the wording used in the definitions of its constructs.

[kcoyle]

@aisaac I wouldn't dislike such a structure for PROF, but if it is adopted then the class name "ResourceDescriptor" seems to contradict that definition.

[kcoyle]

Ah, look at #573 (e.g. Makx's comment)where there was some convergence on renaming ResourceDescriptor to ProfileObject. That removes the implication that what follows is a description of the resource rather than the resource itself.

[kcoyle]

@aisaac as per "I believe that we could leave the matter of harmonizing the 'style' open in 3PWD." As we are within days of the drop dead date for a final version (Sep 17), nothing can be left open at this point unless it will be deferred. And I don't see how we can defer definitions of the vocabulary terms.

[rob-metalinkage]

I've never like "resourceDescriptor" particularly but wanted to distinguish it from the profile and the artefact ) @aisaac is correct in terms of the semantics. Its not a problem to change names as its a tine vocabulary and we dont have a legacy to preserve - so we will publish with the best we can agree on, and what is there already if no agreement is reached - because what is there has survived two feedback cycles in the sense that nothing better has emerged (even if whats there isnt well understood by a few people, unless there is consensus on an improvement we shouldnt change it for the sake of it. ) My preference has always been for a change to a better name for ResourceDescriptor, and I never much liked hasResource anyway. ProfileObject is really really awful however - every thing in a vocabulary could be called ProfileObject and no interpretation is possible.

Given that the prime reason the ResourceDescriptor exists is as a qualified role association a name closer to that might be better. all the other things we want to add to it (as per DCAT distribution), format, conformsTo etc are all clues about its role too that are easier to machine-read than descriptive text )

could people live with ResourceRole and hasResourceRole ?

[nicholascar]

@rob-metalinkage we already have a ResourceRole class (it was formerly Role but we changes it at 2PWD). How about ProfileDistribution, a la DCAT?

[nicholascar]

I propose we close #573 when the issue of the ResourceDescriptor class' name is resolved here.

[rob-metalinkage]

@nicholascar agreed - ResourceRole is already better for the Role descriptor itself so agree best to rename ResourceDescriptor as making it more obvious this akin to DCAT distribution pattern will help, particularly as we have decided not to make profiles dependent on DCAT. We have an informal consensus that the ResourceDescriptor placeholder needs changing.

[aisaac]

@kcoyle about the styling of definitions I meant little things, for example whether we should try to have all property definitions begin by "relates a Profile to X" or "links a Profile to X". I think that reaching such a level of editorial consistency in the text is not needed for PWD, as changing it later wouldn't change the semantics at all.

[aisaac]

@nicholascar no please let's not have the discussion on the naming of ResourceDescriptor here!
My original issue was about changing textual definitions for elements, which do not include ResourceDescriptor. And there's a perfectly valid issue (#573) for discussing this, we should end the discussion there.

[nicholascar]

@aisaac ok, happy to peg names changes for ResourceDescriptor to #573.

[makxdekkers]

@aisaac

@kcoyle about the styling of definitions I meant little things, for example whether we should try to have all property definitions begin by "relates a Profile to X" or "links a Profile to X". I think that reaching such a level of editorial consistency in the text is not needed for PWD, as changing it later wouldn't change the semantics at all.

There is existing practice for the definition of a property to state what the object is, e.g. this is the approach for FOAF, Dublin Core, DCAT (!). It could of course be done differently, e.g. "_This property contains/refers to ..._", but is it worth the extra work?

[aisaac]

@makxdekkers Yes I started to think of this in my suggestions, but I've stopped thinking of it very soon. My point is not to make comments about this now. Basically as soon as the definitions are clearer, I'm happier, whatever stylistic approach they use.

[kcoyle]

@nicholascar Could you say here what the conclusion is? What definitions were included? Because the comments on the PR say that the definitions are not included, so this would then not be due for closing.

[nicholascar]

@kcoyle I'm putting in the PR now and will soon link to it.

[kcoyle]

@nicholascar The conclusions need to be in the closed message. That's because in the future folks will look here for resolutions. Please include the results here, not just a link to the PR (which requires people to dig through for the conclusions to this issue).

[nicholascar]

The following updates to definitions were made in PR #1179:

• prof:Profile - defn harmonised with document's main definition as per suggestion at Issue description
• prof:hasResource - a -> the, stylistic. Full wording in suggestion at Issue description
• prof:isProfileOf - stylised to point to the subject, as per suggestions such as https://github.com/w3c/dxwg/issues/1061#issuecomment-531902623. Sense of the Issue description adopted with the additional stylistic wording
• prof:isTransitiveProfileOf - changed as per discussion here to the simple "A specification this Profile conforms to" since usage note and the axiom present in the vocab cover the particulars
• prof:hasToken - a -> the, stylistic. Wording changed in previous PRs but 'preferred alternative' not removed, as suggested, and the Usage Note & definition not merged. The suggestions here for this property seem sensible to me though and could be implemented completely
• prof:hasArtifact - a -> the, stylistic
• prof:hasRole - changed to remove specifics syntax concerns (SHACL etc.) and to indicate the rols is of the Profile, not the ResourceDescriptor
• prof:isInheritedFrom - stylised to point to the subject
• prof:ResourceRole - changed to refer to the ResourceDescriptor (the domain of the property)

@aisaac do you agree that your suggestions, with additions from Max etc. have been implemented other than perhaps for hasToken? If so, I'll create a new Issue for hasToken wording and close this.

[nicholascar]

Closing since the definitions, with wording changed as noted above, are in the NOTE.