Re: [oslc-core] Some clarifications on Resource Shapes

["Jim Amsden" <jamsden@us.ibm.com>]

Thanks Martin, comments below...

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 "Martin P Pain"
<martinpain@uk.ibm.com>
To:      
 Jim Amsden/Raleigh/IBM@IBMUS
Cc:      
 oslc-core@lists.oasis-open.org
Date:      
 01/07/2016 07:04 PM
Subject:    
   Re: [oslc-core]
Some clarifications on Resource Shapes
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

Looks like a good improvement, and is in
line with my understanding of resource shapes. Just a few suggested tweaks:
 
1. Under "applicability", instead
of "or the shape has no oslc:describesproperty in which case it applies to all associated resources" the
following seems to be a little clearer or easier to read, although I can't
quite put my finger on why: "or the shape has no oslc:describesproperty in which case it applies to all resources associated with that
shape".
<jra>I like it, fixed.</jra>
 
2. Under "applicability" again,
I would change "For all shapes that
"apply to" or describes an associated resource" to (changes
in bold) "For all shapes that "apply to" or describe
a given resource". By definition, if the shape "applies to"
the resource then the resource must be associated with it, so I don't think
the word "associated" adds anything there
<jra>Agreed. But I think
part of the confusion is that if you read the definition of applicability
without knowing about association (which comes after it in the spec), then
this important relationship between association and applicability is not
clear. I would prefer to highlight and enforce the relationship, even though
it is somewhat redundant.</jra>
 
3. Typo in section 6.2 change (association
point 2): "associates a constraining shape with the entity request
or response response resource of a service"
<jra>fixed.</jra>

4. And another in point 3: "the object
value of a property of a some resource"
<jra>fixed.</jra>
 
Martin
 
----- Original message -----
From: "Jim Amsden" <jamsden@us.ibm.com>
Sent by: <oslc-core@lists.oasis-open.org>
To: "OASIS OSLC Core TC Discussion List" <oslc-core@lists.oasis-open.org>
Cc:
Subject: [oslc-core] Some clarifications on Resource Shapes
Date: Thu, Jan 7, 2016 9:03 PM
 
Today on the TC call, there were some discussions about lack of clarity
in the Resource Shapes specification. I make a few changes I hope helps
clear up how shapes are associated with resources, and which associated
shapes apply to the resources.

I update the Terminology section with:

applicability
Shapes associated with a resource apply to that resource if the shape's
oslc:describesproperty
matches the type of the assocated resource, or the shape has no oslc:describesproperty in which case it applies to all associated resources. For all
shapes that "apply to" or describes an associated resource, that
resource should satisfy the constraints defined by those shapes. See Associating
and Applying Shapes for the definition
of how shapes are associated with resources, what associated shapes apply
to a resource, and what it means if multiple shapes apply to a single resource.

association
This specification defines three contexts in which a shape may become associated
with a described resource. The described resource itself may link to a
shape using the property oslc:instanceShape,
the described resource may be the entity request to or response from a
REST service whose service description links to a shape using the property
oslc:resourceShape,
or the the resource may be the object value of a Property whose oslc:valueShapelinks
to the constraining shape. More than one shape may become associated with
a described resource in a given context. The shapes associated with a resource
are the set of shapes to be checked for applicability. Not all the associated
shapes are necessarily applicable. Refer to the definition of applicability
above. 

The previous definitions appeared incomplete.

I changed the first paragraph in section 6.2 Associated and Applying Shapes
to:

In general, the relation between shapes and resources is many-to-many.
Given a resource R there MAY be zero or more shapes S associated
with it. This specification defines three ways to associate shapes with
a resource, namely using oslc:instanceShape,
oslc:resourceShape,
and oslc:valueShape.
Other specifications MAY define additional mechanisms.

1. Resource oslc:instanceShapeResourceShape - directly associates a constraining shape with a resource.
2. Service oslc:resourceShapeResourceShape - associates a constraining shape with the entity request or response response resource of a service (e.g., a creation or query service).
3. Property oslc:valueShapeResourceShape - associates a constraining shape with the resource that is the object value of a property of a some resource.

Not
all shapes associated with a resource are necessarily applicable to it.
Let S be associated with R. S is said to apply to R in the following
two cases:

This more complete and consistent with the updated definitions of applicability and association.

Anyone see any problems with these updates?

 

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575

 
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php