UCO should hint at Facet associations

[ajnelson-nist]

Background

At present, any instance of a Facet is freely associable with any instance of a UcoObject. This is in support of duck typing, where being a Foo implies having behaviors like a Foo, but having behaviors like a Foo does not necessarily imply being a Foo. However, at present, UCO has no encoding of this. "Foo" has no association with "FooFacet" stronger than any other "BarFacet" - e.g., uco-observable:File and uco-observable:FileFacet are as strongly related by structural design as uco-observable:File and uco-observable:URLFacet. The string pattern-matching is clear, but would not cover cases where Facets should be associated with non-matching name patterns, like uco-identity:Person and uco-identity:SimpleNameFacet.

There is a mechanism to express this in OWL. For File and FileFacet, this block of Turtle states that "If a thing is a File, there exists one FileFacet linked with hasFacet."

uco-observable:File
	rdfs:subClassOf [
		a owl:Restriction ;
		owl:onProperty uco-core:hasFacet ;
		owl:qualifiedCardinality "1"^^xsd:nonNegativeInteger ;
		owl:onClass uco-observable:FileFacet ;
	] ;
	.

(Syntax can be reviewed by checking for ObjectExactCardinality in OWL 2 Web Ontology Language Mapping to RDF Graphs.)

Adding this encoding does not cause data where there's a File with no FileFacet to be declared invalid. OWL's open-world assumption leaves it fine to not record a FileFacet.

SHACL is not an appropriate mechanism to make such an expression. This statement of existence can be represented with sh:qualifiedValueShape, but there's nothing being constrained, except the uniqueness of the specific facet type (i.e, no File can have two different FileFacets). Specific facet type uniqueness is left out of scope of this proposal, and requires resolution of Issue 595. The present proposal intends only to hint an inheritable association.

Requirements

Requirement 1

UCO SHOULD hint the Facet classes associated with any UcoObject subclass.

Requirement 2

The hinting mechanism MUST support arbitrary Facet associability---that is, if a pattern association is not present (like a "Foo" and "FooFacet" being related by suffixing), hard-coding an association should be possible.

Requirement 3

The hinting mechanism MUST NOT impede other abilities to associate Facet instances with UcoObject instances.

Risk / Benefit analysis

Benefits

This proposal helps to remove some of the obfuscation caused by housing properties in Facets rather than directly on UcoObjects. Before this proposal, the tie between a File and the fileName property are as strong as the tie between a File and a latitude value.

Adoption of this proposal enables focused discovery of properties entailed by Facets from parent classes. For instance, the CASE JSON-LD Stubs repository shows a stub for uco-observable:ArchiveFile here. The Facet hinting in this proposal enables linking in the directly associated ArchiveFileFacet, as well as the parent class's FileFacet. Both associations were drawn from the "Foo"/"FooFacet" pattern-match, which will be part of the implementation this proposal begins.

Reviewing the Facet hints also provides an opportunity to review Facets that have no current associated UcoObject subclass, clearing up currently unclear and/or forgotten use cases.

Risks

This proposal brings more OWL structural syntax into UCO. This risk and syntactic complexity increase is suggested as acceptable because the need is believed inappropriate to meet with SHACL.

Concerns with accidental inference capabilities have been noted by some UCO Ontology Committee members. The restriction illustrated in the proposal background has the following inferential effects:

• On a File, if there are two FileFacets linked with hasFacet, the two FileFacets are inferred to be the same individual. This is actually in line with previously expressed, but not yet encoded, understandings that "Specific" Facet classes are meant to be unique in typing on their "Host" objects. (Again, a universal SHACL review mechanism for this uniqueness is deferred until after Issue 595 is adopted.)
  • On any non-File UcoObject instance, if there are two FileFacets linked with hasFacet, the two FileFacets are NOT inferred to be the same individual. While not desirable, this is consistent with the current state of UCO. (This would also be resolved after Issue 595.)
• If a File has no FileFacet linked with hasFacet, there is NO automatic creation of a FileFacet node.
• If a File has some non-FileFacet linked with hasFacet, it is NOT inferred to be a FileFacet. (This would happen if owl:allValuesFrom were used.)
• If some non-File thing has a FileFacet linked with hasFacet, the thing is NOT inferred to be a File. (This would happen if a certain owl:equivalentClass construction were used. The owl:Restriction used in this proposal is only "if", not "only if" or "if and only if".)

Last, while the "Foo"/"FooFacet" pattern will generate many of the owl:Restrictions, several Facet classes don't match this pattern, and will require manual attention and association. A comment following this proposal will list the known non-mechanically-associable Facets subclasses.

Competencies demonstrated

The key competency generated in this proposal is support for mechanical discovery of properties of UcoObjects ("domain objects") that have been obscured by separation into Facets. The JSON-LD stubs repository, especially with its ArchiveFile demonstration, is left as the demonstration of this new competency.

Solution suggestion

• Generate the owl:Restrictions noted in the background for all "Foo"/"FooFacet" pairs. Do so by importing the script facet_cardinalities_ttl.py.
  • This proposal is not suggested to wait for the entire resolution of hinting currently-unassociated Facets.
• Adapt facet_cardinalities_ttl.py for an idempotent usage process - namely, not generating owl:Restrictions if it already exists in UCO.
  • This is slightly complicated by owl:Restrictions being syntactically required to be blank nodes.
• Integrate the adapted facet_cardinalities_ttl.py into CI, to catch when a new "Foo"/"FooFacet" pair is added but an owl:Restriction is forgotten.
  • The test update is likely to be: Generate a graph of new owl:Restrictions, and fail the test if any are generated, with a gentle suggestion to copy them in.

Coordination

• Tracking in Jira ticket OCUCO-325

• Administrative review completed, proposal announced to Ontology Committees (OCs) on 2024-09-19
• Requirements to be discussed (informally) in OC meeting, 2024-09-26
• Requirements to be discussed in OC meeting, 2024-10-24

• Requirements Review vote has not occurred

• Requirements development phase completed.
• Solution announced to OCs on TODO-date
• Solutions Approval to be discussed in OC meeting, date TBD
• Solutions Approval vote has not occurred

• Solutions development phase completed.
• Backwards-compatible implementation merged into develop for the next release
• develop state with backwards-compatible implementation merged into develop-2.0.0
• Backwards-incompatible implementation merged into develop-2.0.0 (or N/A)
• Milestone linked
• Documentation logged in pending release page
• Prerelease publication: CASE develop branch updated to track UCO's updated develop branch
• Prerelease publication: CASE develop-2.0.0 branch updated to track UCO's updated develop-2.0.0 branch

[ajnelson-nist]

These Facet subclasses do not follow the "Foo"/"FooFacet" name pattern with the state of CASE 1.3.0 [sic.].

• action:ActionArgumentFacet
• action:ActionEstimationFacet
• action:ActionFrequencyFacet
• analysis:ArtifactClassificationResultFacet
• core:ConfidenceFacet
• identity:AddressFacet
• identity:AffiliationFacet
• identity:BirthInformationFacet
• identity:CountryOfResidenceFacet
• identity:EventsFacet
• identity:IdentifierFacet
• identity:LanguagesFacet
• identity:NationalityFacet
• identity:OccupationFacet
• identity:OrganizationDetailsFacet
• identity:PersonalDetailsFacet
• identity:PhysicalInfoFacet
• identity:QualificationFacet
• identity:RelatedIdentityFacet
• identity:SimpleNameFacet
• identity:VisaFacet
• location:GPSCoordinatesFacet
• location:LatLongCoordinatesFacet
• location:SimpleAddressFacet
• observable:AccountAuthenticationFacet
• observable:AntennaFacet
• observable:CompressedStreamFacet
• observable:DataRangeFacet
• observable:EXIFFacet
• observable:EncodedStreamFacet
• observable:EncryptedStreamFacet
• observable:ExtInodeFacet
• observable:ExtractedStringsFacet
• observable:FilePermissionsFacet
• observable:FragmentFacet
• observable:MftRecordFacet
• observable:NTFSFilePermissionsFacet
• observable:PathRelationFacet
• observable:PropertiesEnumeratedEffectFacet
• observable:PropertyReadEffectFacet
• observable:SendControlCodeEffectFacet
• observable:StateChangeEffectFacet
• observable:TwitterProfileFacet
• observable:UNIXFilePermissionsFacet
• observable:UNIXVolumeFacet
• observable:ValuesEnumeratedEffectFacet
• observable:WhoisContactFacet
• observable:WindowsVolumeFacet
• observable:X509V3ExtensionsFacet
• tool:BuildFacet

[sbarnum]

I am all for having some sort of hinting to associate potential or likely connections between particular UcoObject classes and certain Facets.

It is kind of late as I am reviewing this so I am not 100% confident in my read of the semantic logic and inferencing implications of the proposed approach but these two issues would be my main concern that any solution must avoid:

If a File has no FileFacet linked with hasFacet, there is NO automatic creation of a FileFacet node.

If some non-File thing has a FileFacet linked with hasFacet, the thing is NOT inferred to be a File. (This would happen if a certain owl:equivalentClass construction were used. The owl:Restriction used in this proposal is only "if", not "only if" or "if and only if".)

If you have verified that these are not issues with the proposed approach then my main concerns are assuaged.

If the following is the only real semantic issue then I agree that this is not a deal-breaker and is likely worth eating in order to get the hinting:

On a File, if there are two FileFacets linked with hasFacet, the two FileFacets are inferred to be the same individual. This is actually in line with previously expressed, but not yet encoded, understandings that "Specific" Facet classes are meant to be unique in typing on their "Host" objects. (Again, a universal SHACL review mechanism for this uniqueness is deferred until after Issue 595 is adopted.)
On any non-File UcoObject instance, if there are two FileFacets linked with hasFacet, the two FileFacets are NOT inferred to be the same individual. While not desirable, this is consistent with the current state of UCO. (This would also be resolved after Issue 595.)

[ajnelson-nist]

I am all for having some sort of hinting to associate potential or likely connections between particular UcoObject classes and certain Facets.

It is kind of late as I am reviewing this so I am not 100% confident in my read of the semantic logic and inferencing implications of the proposed approach but these two issues would be my main concern that any solution must avoid:

If a File has no FileFacet linked with hasFacet, there is NO automatic creation of a FileFacet node.

If some non-File thing has a FileFacet linked with hasFacet, the thing is NOT inferred to be a File. (This would happen if a certain owl:equivalentClass construction were used. The owl:Restriction used in this proposal is only "if", not "only if" or "if and only if".)

If you have verified that these are not issues with the proposed approach then my main concerns are assuaged.

The verification is in this Gist.