sbarnum
commented
2 years ago This issue has nothing to do specifically with Facets.
I will save comments on the myriad of issues, incomplete understanding and mischaracterizations of Facets in Issue 438 for attaching to that issue. I will mention one issue with 438 here as it likely has bearing. 438 asserts a misunderstanding/mischaracterization that Facets are specifically designed and present to support Duck typing. This is incorrect. The design approach of Facet classes and their use with the core:hasFacet property on UcoObjects is about far more than Duck typing or ObservableObjects in general. The Facet pattern has specific purpose that I will explain in comments on 438 but it predates the CASE (DFAX at the time) consensus requirement for Duck typing. Its prior existence simply offered a very straightforward way to support Duck typing when the requirement arose. Even if the CASE requirement for Duck typing were removed, Facets would still be required for UCO. I believe that Section 5 of the UCO Design Document explains the intent of Facets beyond Duck typing.
The issue here is simply to do with rdfs subclassing combined with SHACL property shapes and how they interact with subclassing hierarchies. There is NOTHING special about the core:Facet class (or subclasses) from the rdfs/owl/shacl perspective. It is only a little special in its level of abstraction and intended purpose for users. Facet is simply a class and all of the Facet subclasses are simply subclasses.
- DigitalAddressFacet
- MACAddressFacet
- WiFiAddressFacet
could just as easily be
- Vehicle
- Automobile
- Sedan
The Facet classes simply apply to the core:hasFacet property just like the vehicle classes could apply to a methodOfTransport property.
There seems to be two potential issues raised here:
- Users could potentially be confused by redundant property shape assertions at multiple levels of a class hierarchy (once again NOTHING specifically to do with Facet)
- Users could potentially be confused by how subclassing works in general
The first issue is very simple to address. While redundant property shape assertions are completely valid in SHACL they are not required and can simply be removed from the subclasses leaving only the shape at the top (ROOT) of the hierarchy. The large majority of users will be looking to the autogenerated documentation (rather than directly at the turtle) to understand UCO. This documentation clearly shows the relevant properties for each class including those "inherited" at each level of its position in a class hierarchy. So, with the property shape for addressValue asserted at the DigitalAddressFacet level it will still clearly be shown as a single occurrence when looking at the documentation for WiFiAddressFacet. The documentation also shows (right at the top of the page) where a particular class sits in a class hierarchy including not only superclasses but also subclasses which should make it straightforward for a user to find the most appropriate class for what they are trying to express. This documentation should mean that there is little potential for confusion on number 1 once redundant shapes are removed. Anyone looking directly at the turtle to understand UCO should not be confused by number 1 or number 2 above and if they are then all bets are off anyway as they will be confused by far bigger things than this.
If the properties are in the "Root" end, different problems may arise from UCO inability to enforce constraints at multiple different levels of the
Facetsubclass hierarchy.
I do not believe this is true. As long as the differential constraints are more rather than less restrictive as you descend the class hierarchy then there should be no problems and this is exactly as SHACL is designed to work.
Suppose
addressValuewas given a property shape inDigitalAddressFacet, and that shape was not copied to the leaf nodes. Then supposeMACAddressFacetdefines an independent, supplementary property shape that constrainsaddressValueto follow a certain regex (hex-byte, colon, hex-byte, colon, and so on). AWifiAddress(notFacet) instance could be defined like this and pass SHACL validation:
{
"@id": "kb:wifi-address-3",
"@type": "observable:WifiAddress",
"core:hasFacet": {
"@type": "observable:DigitalAddressFacet",
"observable:addressValue": "root@example.org"
}
}This would pass with an email address being the value "of" a
WifiAddressbecause the subclass hierarchy ofDigitalAddress--MACAddress--WifiAddressis completely decoupled fromDigitalAddressFacet--MACAddressFacet--WifiAddressFacet.
This decoupling is fundamentally necessary to support Duck typing. In Duck typing you may start with an ObservableObject object with one or more observable facet subclasses on it to characterize the details you know even if you are unsure yet what object(s) you are describing. You could then analyze what facets and properties are on the generic object and reach some conclusion as to what type of object or objects there are and then define these specific object types (e.g., MACAddress) and attach the relevant facet(s) on it. This is the entire concept of Duck typing. Of course, the current design and implementation in UCO does not require any user to follow Duck typing if it is not appropriate. If a user knows what type of object they are creating, they can simply create the object (e.g., WiFiAddress) with the appropriate facet(s) (e.g., WiFiAddressFacet) directly right from the start. I suspect the non-Duck typing approach will be used FAR more than the Duck typing approach but supporting Duck typing has been a fundamental requirement of CASE since its initiation.
The above json example would be perfectly legal if the propertyshape for addressValue at the DigitalAddressFacet provided no further constraint than xsd:string. And this is as it should be as it is the basis for RDFS subclassing and applying SHACL to it. The user of an email address string in a DigitalAddressFacet on a WiFiAddress ObservableObject would be a perfect example of a user drawing poor conclusions from a Duck typing situation where they looked at the email address string in the DigitalAddressFacet and thought "yeah, that looks like a WiFiAddress. They could have easily made better conclusions. That also does not mean that the user should not have used EmailAddressFacet rather than DigitalAddressFacet. This is a fundamental issue of users understanding subclassing and once again has NOTHING to do with Facets specifically. Using the vehicle analogy, if a user desired to express a Trip that used a 4-cylinder Toyota Camry they could easily express it as:
{
"@id": "kb:trip-1",
"@type": "Trip",
"methodOfTransport": {
"@type": "Vehicle",
"engineCylinderCount": 4
}
}when it would be more appropriate to express as:
{
"@id": "kb:trip-1",
"@type": "Trip",
"methodOfTransport": {
"@type": "Sedan",
"engineCylinderCount": 4
}
}If methodOfTransport had a 0..* cardinality similar to core:hasFacet It would also be completely possible for a user to express this as:
{
"@id": "kb:trip-1",
"@type": "Trip",
"methodOfTransport": [
{
"@type": "Vehicle",
"engineCylinderCount": 4
},
{
"@type": "Automobile",
"engineCylinderCount": 4
},
{
"@type": "Sedan",
"engineCylinderCount": 4
}
]
}This is simply a matter of users understanding subclasses and the fact they should use the most appropriate one to their needs. This has NOTHING specifically to do with Facets.
I do not think we can do much about number 2 above. Understanding how subclassing works is a conceptual issue at a far broader scope than specifying UCO.
Net-Net: I believe this Issue misidentifies the underlying potential issues in play, very incorrectly asserts this as a problem specifically with Facet classes, and mischaracterizes the risks in play and potential solutions.
The core issues in play are that
- Redundant SHACL property shapes in a class hierarchy could cause significant use confusion. I personally do not believe that there is significant risk of this but the issue is simple to address by removing the redundant shape assertions leaving only the first one highest in the hierarchy
- Users may be confused by how subclasses work and choose a less than optimal level in a given subclass hierarchy. I do not think that this is an issue for UCO to attempt to resolve as it is much broader than UCO. If you wish to mitigate the risk of a lacking understanding of subclassing and duplicatively asserting multiple classes with the same property within a class hierarchy (as shown in the last example above) you could add the sort of textual caveat proposed in the Solution Suggestion above but it would need to be done for ALL subclasses not just for Facet subclasses as this is a general subclassing issue that is NOT specific to Facets. I personally do not think this is a good idea. It itself is likely to cause as much or more confusion than it solves and sets a poor precedent for adding such extraneous detail to our definitions to cover a users potential inadequate understanding of modeling concepts.
ajnelson-nist
Note from OC Chair: The risk of this proposal is between low and moderate, so normally would not merit a Fast-Track review. However, the usage pattern being addressed may be more harmful than good to leave in 1.0.0. If OC members object to fast-tracking this, it will be staged as a 2.0.0 proposal.
Background
There are a few
core:Facetsubclasses that have a parent class between the class andcore:Facet. One example isobservable:WifiAddressFacet, an eventual subclass ofobservable:DigitalAddressFacet. In that instance, and if I recall correctly some others as well, property shapes are defined redundantly onDigitalAddressFacet,MACAddressFacet, andWifiAddressFacet. Their total definitions in today'sdevelopbranchobservable.ttlare:The property shape for
observable:addressValueis repeated across all three of those subclass layers. This creates a point of user confusion, potential incompatibility under RDFS expansion, and further potential incompatibility under OWL expansion.Take this snippet of data:
If a user performed RDFS expansion, the following classes would be added by merit of
rdfs:subClassOfstatements (spelled here in leaf-to-owl:Thingclass order):If a user is unaware of RDFS expansion, they might feel obligated to create all of the intermediary
Facets, and redundantly store the data:This would be a nuisance data behavior for UCO to require (causing much data bloat). It is also unnecessary because of something not yet encoded in UCO, but intended according to several conversations over the years, that there should only be one instance of class
XFacetattached to each instance of classX. This can be requested in a way with aowl:qualifiedCardinality 1oncore:hasFaceton eachUcoObjectsubclass, but it would be a supreme nuisance to users to enforce in SHACL.Under RDFS expansion, we end up with three independent instances of
observable:DigitalAddressFacetattached tokb:wifi-address-2. This situation gets worse if a user doesn't realize the RDFS expansion, and further thinks they can use the extraaddressValueslots in "Independent" parentFacetclasses to stash other data, like a second MAC Address on a two-NIC server:The
Facetsubclasses might be helpful for visualizing subclass hierarchies. However, the redundant storage of properties outside of the "Leaf"Facetsubclasses ends up, through the above illustrations, being harmful to users.These significantly confusing patterns are one of the motivations for doing away with
Facets altogether. However, in the event that Issue 438 does not pass, this proposal is offered for consideration.Requirements
For reasons explained in the Risks section, there is no technical solution possible while
Facets exist as a parallel hierarchical class structure to theUcoObjectclass hierarchy.Requirement 1
Requirement 1 has been stricken. It was previously:
Requirement 2
UCO must not wholly repeat property sh:PropertyShapes between subclasses - that is, define a completely matching set of SHACL constraints in a class C and subclass D.
Risk / Benefit analysis
Benefits
Facetsubclass hierarchy, or even use theFacetsubclass hierarchy if there is no need.Facets, users that follow the guidance would be less likely to run into RDFS expansion issues that violate the not-yet-encoded design intent of "An instance ofUcoObjectclassXshould have exactly oneXFacet."Risks
The risks pertain to continued usage of
Facets, and not to any implementation changes due to this proposal.The risks stem from not being able to recommend de-duplication of properties on
Facets in UCO's current implementation. Putting all of the property shapes into just one "End" of theFacethierarchy has potential for confusion, whether the end is the leaf subclasses, or the "root" subclass.If the properties are in the "Leaf" end, it is difficult to encode in SHACL how to say what each leaf must have in terms of property shapes without inducing the usage confusion above. ("When do I create a
WifiAddressFacetAND aDigitalAddressFaceton one node?" will arise if users miss language in the class documentation comments.) This would be a breakage with most benefits of class hierarchies.If the properties are in the "Root" end, different problems may arise from UCO inability to enforce constraints at multiple different levels of the
Facetsubclass hierarchy. SupposeaddressValuewas given a property shape inDigitalAddressFacet, and that shape was not copied to the leaf nodes. Then supposeMACAddressFacetdefines an independent, supplementary property shape that constrainsaddressValueto follow a certain regex (hex-byte, colon, hex-byte, colon, and so on). AWifiAddress(notFacet) instance could be defined like this and pass SHACL validation:This would pass with an email address being the value "of" a
WifiAddressbecause the subclass hierarchy ofDigitalAddress--MACAddress--WifiAddressis completely decoupled fromDigitalAddressFacet--MACAddressFacet--WifiAddressFacet.Last, it is not clear how to reconcile these issues with an object that is rightly one of the
UcoObjectclasses corresponding to one of the intermediaryFacetsubclasses. (And likewise for any extension subclass anywhere along either class hierarchy.) If the correspondingFacethas no property shapes, the user has no guidance or validation available for metadata meant to be attached to the object. This is also a reason that the intermediary subclass hierarchy ofFacets probably can't just be deleted outright.The proposer believes this is a design flaw with
Facets, and encourages further consideration of Issue 438. None of this proposal would be necessary if properties were directly onUcoObjectsubclasses.Competencies demonstrated
The potential errors we wish to prevent are demonstrated in the background and risks.
Solution suggestion
Facetsubclasses. Append this string statement to their documentation strings, as a standalone line: "The most specific subclass of Facet should be used for the corresponding UcoObject. No parent class of this Facet should also be instantiated on this object."The multi-level
Facetsubclasses can be identified with this query:From UCO's current
developstate (ba9da19), these classes would need that annotation:Coordination
develop