oslc-op / oslc-specs

OSLC OP specifications and notes
https://open-services.net/specifications/
24 stars 9 forks source link

dcterms:contributor@ChangeRequest either has foaf:Person range or not #76

Closed berezovskyi closed 4 years ago

berezovskyi commented 5 years ago

CM 3.0 CS02 says that dcterms:contributor has range foaf:Person. In the comment it then says that it might not necessarily be the case. This is wrong. Range is either foaf:Person or Resource with a note that it MAY be foaf:Person in most cases.

RM 2.1 CS02 got it right: http://docs.oasis-open.org/oslc-domains/oslc-rm/v2.1/cs01/part2-requirements-management-vocab/oslc-rm-v2.1-cs01-part2-requirements-management-vocab.html#requirement

berezovskyi commented 5 years ago

@jamsden for the RefImpl work, I consider the Range to have normative precedence over the comment and will set the dcterms:contributor the range foaf:Person in the Lyo domain spec for CM.

cc @jadelkhoury

berezovskyi commented 5 years ago

Same problem for dcterms:creator

jamsden commented 5 years ago

This is the same language that's used in core 3.0. oslc:Range description in ResourceShapes says: "For object properties, specifies what the target resource type is expected to be, but that is not necessarily the case.". So I think we are fine. Closing

berezovskyi commented 5 years ago

No, this might be fine language for humans but software does not work like that. I either fail the validation if the property is not a foaf:Person or not. From the description, I think we need to make the property range in the shape to be a Resource.

jamsden commented 5 years ago

Don't agree. This was common practice in core and other specs, and was the intention of ResourceShapes oslc:range. I'd rather be conservative and leave it as it was in 2.0.

berezovskyi commented 5 years ago

But then we agree that oslc:range becomes meaningless garbage. oslc:range X might mean that a resource is of type X or not, whatever!

Furthermore, I want to see us migrate to SHACL or ShEx in the future and their semantics are defined rather well (range X means that object MUST be of type X). We won't be able to do that with such a lax approach.

For the record (https://www.w3.org/Submission/2014/SUBM-shapes-20140211/#range):

For object properties, oslc:range is used to specify an allowed rdf:type of the object resource.

Which means if the the rdf:type is not in the range, it is not allowed. QED (https://en.wikipedia.org/wiki/Contraposition).

berezovskyi commented 5 years ago

dcterms:contributor shall be oslc:Any.

jamsden commented 5 years ago

Well, not meaningless garbage, but rather recommended expectation while preserving open-world flexibility. Remember, these are constraints on an open vocabulary in a context, not structure definitions that apply universally.

Regarding migration to SHACL or ShEx, that may be a better technology solution. But 1) its an option OSLC already supports, 2) we have existing ResourceShapes from OSLC 2.0 we have to maintain and 3) its really a business decision for what servers want to implement. The business case to migrate might be weak - a lot of things would break, for what new value?

berezovskyi commented 5 years ago

these are constraints on an open vocabulary in a context, not structure definitions that apply universally.

Fully agree. And in that context, those constraints shall hold (be true). What the description says, on the other hand, is that the constraint may or may not hold (T v F). Which is a dictionary definition (strictly speaking, T v !T, which is equivalent to T v F) of a https://en.wikipedia.org/wiki/Tautology_(logic) (aka nonsense, falsehood, fake news).

Therefore, I suggest that we either amend the description to remove the possibility of a property being out of foaf:Person range or amend the range to be oslc:Any.

ndjc commented 5 years ago

We have previously discussed this. We must preserve compatibility with existing implementations and specs, so changing oslc:range to rdfs:range with its strict constraints is unacceptable. The semantics for oslc:range are deliberately weak as Jim has described, but it is not meaningless noise, but hints for a user interface such as a report builder. Clients should use defensive programming to ensure they handle cases where the target resource does not have the expected type.

In summary, oslc:range is guidance, not a constraint.

berezovskyi commented 5 years ago

First, I am not suggesting RDFS (nitpick: RDFS has inference semantics, and they are the opposite of strict).

Second: academically speaking, if the constraints are not strict, we call them undefined. Again, see about logical tautology.

Finally, to the subject matter: what you are describing is a range hint. Not a range restriction. If you wish to amend the Shape spec and introduce hints, fine. However, the semantics of OSLC Shapes are quite clear now: if the RDF type of the object is not within the oslc:range of the property, the resource fails to conform to the shape (the validation library will not return true when you validate an incoming RDF of such form).

Clients should be ready to get something that does not conform to the shape. But if I were to build one, I would just set such a property to null while unmarshalling (Lyo will fail if such range mismatch happens inside a LocalResource).

In other words, I think we need to get this right.

ndjc commented 5 years ago

From OSLC Core 3.0 specs:

<#range> a oslc:Property ; oslc:name "range" ; oslc:propertyDefinition oslc:range ; oslc:range rdfs:Class ; oslc:occurs oslc:One-or-many; dcterms:description "For object properties, specifies what the target resource type is expected to be, but that is not necessarily the case."^^rdf:XMLLiteral ; oslc:valueType oslc:Resource ; oslc:representation oslc:Reference ; oslc:readOnly true .

So, yes, this is a hint, not a restriction; this was a deliberate loosening of the spec wording in 3.0 to allow for the many, many places that used the wording 'expected, but not necessarily the case'.

ndjc commented 5 years ago

For the specific case of foaf:Person, note that the range was almost certainly the wrong one to use anyway. It should have been the parent class foaf:Agent; a software bot could be the agent submitting or modifying change requests.

berezovskyi commented 5 years ago

Thanks Nick, I didn’t know that the restriction was relaxed. I also agree regarding the actual value of the range to be set to foaf:Agent.

From 2.0:

Now please note that the semantics of range are well-defined (disjunctive restriction) and how the behaviour of clients and servers is well-defined in the event the restriction is violated and the resource does not conform to the shape.

What was done between then and the current draft is quite bad, as the new definition loses any meaning (truth or falsehood is tautology, once again). By definition, any shape validation library should have a function validate(resource, shape) { return true;}. The old definition allowed you do real validation and have a switch if valid ... else ...

I would like this rewording be reversed.

-- /Andrew (from phone)

25 juli 2019 kl. 20:11 skrev Nick Crossley notifications@github.com<mailto:notifications@github.com>:

For the specific case of foaf:Person, note that the range was almost certainly the wrong one to use anyway. It should have been the parent class foaf:Agent; a software bot could be the agent submitting or modifying change requests.

— You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHubhttps://github.com/oslc-op/oslc-specs/issues/76?email_source=notifications&email_token=AAAPZXTFMYRPU2OA4XVKDWLQBHUFHA5CNFSM4H6WTF4KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD22KIFA#issuecomment-515154964, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AAAPZXWXQU4ET2UDYTTI6VLQBHUFHANCNFSM4H6WTF4A.

jamsden commented 5 years ago

You're absolutely right - if resource shapes are suppose to define constraints that can be validated, not hints. What would it mean to validate a hint?

Unfortunately it is too late to fix this ResourceShape validators will need to understand that oslc:Range is a "hint" and print warnings, not errors if there's a mismatch. That's an ugly special case, but corresponds to common practice and existing implementations. I think we're stuck with it.

Note however that OSLC allows other ways of specifying constraints. Server implementations are free to implement them if there's client demand.

berezovskyi commented 5 years ago

You're absolutely right - if resource shapes are suppose to define constraints that can be validated, not hints. What would it mean to validate a hint?

Exactly. If you look at http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.362.5294&rep=rep1&type=pdf, Arthur Ryman writes:

A resource shape is a set of grammar rules, expressed in RDF, an RDF graph must comply with to be correct. A resource shape lists the properties that are expected or required in a graph, their occurrence, range, allowed values, etc.

Now, fixing the stuff:

Unfortunately it is too late to fix this ResourceShape validators will need to understand that oslc:Range is a "hint" and print warnings, not errors if there's a mismatch.

I don't see anything wrong with it. We expand the range from foaf:Person to either any resource or foaf:Agent and make it strict. And then we say that it is not guaranteed that all shape-conformant resources will be accepted by the Creation Factory or that the GET will return a resource in full conformance. In other words, every OSLC Client shall program defensively.

I think we're stuck with it.

I don't think so. We need to maintain backwards compat, but not forward compat. We can require implementors to do some work before becoming OSLC 3 compliant. Both foaf:Agent and any resource ranges would be backwards-compatible.

jamsden commented 5 years ago

There are many properties in the OSLC specs that have oslc:range oslc:AnyResource but have descriptions that say what the expected range is, but that it is not necessarily the case. This was done to not overly constrain the specs, causing undesirable implementation restrictions in some cases.

It appears we forgot this in some cases, and dcterms:contributor seems to be one of them. That's probably an error resulting from common practice.

As Nick suggested, we tried to overcome this by weakening the definition of ResourceShape oslc:range property to be a "hint". We also added a bunch of oslc:range properties with more specific types in order to make the resource shapes more meaningful.

I believe this was wrong and as Andrew suggest should be reverted.

Regarding dcterms:contributor, we can either set that to oslc:AnyResource or oslc:Agent. oslc:AnyResource would probably be the best choice.

However, we will also need to go back through all the shapes and make sure we didn't add oslc:range properties, as well as remove the descriptive text that indicated what the expected range is even though the specified range is AnyResource. There could be a lot of these, I quickly found one in the CM 3.0 spec.

berezovskyi commented 5 years ago

I slept on this and have a new idea (more of an obvious question that an idea but still). I was writing a few shapes by hand today and was using https://www.w3.org/Submission/2014/SUBM-shapes-20140211/ as a reference. Why don't we just remove the resource shape part from the OSLC 3 specs altogether and put a normative reference instead?

jamsden commented 5 years ago

ResourceShapes were part of the OSLC 2.0 specification. w3c ResourceShapes 2.0 was an attempt to migrate what was in OSLC 2.0 as a separate w3c specification. This was replaced by Shacl and the work done on w3c ResourceShapes 2.0 was migrated into OSLC Core 3.0.

We have to retain ResourceShapes because it was part of OSLC 2.0.

jamsden commented 5 years ago

We discussed this on a previous TSC call, and I recall @ndjc arguing for no change - we keep the hint semantics for oslc:range because it provides information to things like Jazz Reporting Service Report Builder (and possibly dialogs that support resource update), but still don't overly constrain servers.

ResourceShape validators would have to know that this is intended to be a hint and issue a warning not an error if the resource doesn't match the type.

Where are we on this? Close no change?

berezovskyi commented 5 years ago

I disagree.

First, OSLC 2 had proper oslc:range semantics. Not reverting it would be a breaking change.

Next, the use in the IBM product you mentioned is internal and not on the OSLC REST interface. We can define an oslc:rangeHint predicate for that and the product can update its internal logic. No impact on the OSLC clients.

I am in favour of reverting the hint changes made in the v3 of the spec.

-- /Andrew (from phone)

9 aug. 2019 kl. 13:58 skrev Jim Amsden notifications@github.com<mailto:notifications@github.com>:

We discussed this on a previous TSC call, and I recall @ndjchttps://github.com/ndjc arguing for no change - we keep the hint semantics for oslc:range because it provides information to things like Jazz Reporting Service Report Builder (and possibly dialogs that support resource update), but still don't overly constrain servers.

ResourceShape validators would have to know that this is intended to be a hint and issue a warning not an error if the resource doesn't match the type.

Where are we on this? Close no change?

— You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHubhttps://github.com/oslc-op/oslc-specs/issues/76?email_source=notifications&email_token=AAAPZXSG7YOFMM2RMVBCQBDQDVLWRA5CNFSM4H6WTF4KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD36OXYQ#issuecomment-519891938, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AAAPZXQRCNUZM7RO4YJFMETQDVLWRANCNFSM4H6WTF4A.

berezovskyi commented 5 years ago

This is hilarious: we actually managed to break not one but two rules of our own while handling the range updates: https://archive.open-services.net/bin/view/Main/OslcCoreSpecification.html#Rules_for_new_versions_of_OSLC_s. First:

If you believe that you need a property but cannot agree on the value-type, then this is a strong indication that you should not attempt to standardize on the property. Once you decide on a value-type you are stuck with it forever.

Nice! Someone thought about this before and was more blunt: if you don't know whether foaf:Person is the right range or not, don't even add the property until you make up your mind!

When defining resources, do not remove, change the meaning or the value-type of any properties that you defined in earlier versions of the specification. You can add new properties but not change those that already exist.

Yep :)

berezovskyi commented 5 years ago

Here is my suggestion:

I hope you agree that all the steps except the change of the range are reasonable. Now, to the oslc:range change. We use the following wording to motivate it:

Finally, we restore the strict definition of the range to be 100% compatible with 2.0.

I add this message to the agenda for the meeting, we can discuss it next Thu and once again when Nick is back.

berezovskyi commented 4 years ago

After discussion with @ndjc today the updated suggestion is not to change the oslc:range on the offending properties to oslc:AnyResource but to add an extra <> oslc:range oslc:AnyResource triple to the offending shape property descriptions, effectively making the description equivalent to:

{R} U Any === Any

Where R is a current range value on the properties with a diluted description and Any is the powerset of all possible ranges, represented in OSLC via the oslc:AnyResource property.

ndjc commented 4 years ago

Actually, it should be oslc:Any - not oslc:AnyResource. The latter is an enum value for the representation.

jamsden commented 4 years ago

Did this get done?

berezovskyi commented 4 years ago

Nope, please propose the change

-- /Andrew (from phone)

On 20 Jan 2020, at 21:32, Jim Amsden notifications@github.com<mailto:notifications@github.com> wrote:

Did this get done?

— You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHubhttps://github.com/oslc-op/oslc-specs/issues/76?email_source=notifications&email_token=AAAPZXUU2CDYM7NMIEC5B23Q6YC4BA5CNFSM4H6WTF4KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEJNX7UY#issuecomment-576421843, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AAAPZXURIKLVTFMQZ5PET5LQ6YC4BANCNFSM4H6WTF4A.

jamsden commented 4 years ago

Fixed for Core