sh:description should be used in place of rdfs:comment on property shapes

[ajnelson-nist]

Background

Classes and properties in UCO currently use rdfs:comment to provide their definitions.

At the time of the conversion to SHACL, some sh:PropertyShapes also provided descriptions of property-class associations. Those were also encoded with rdfs:comments.

SHACL provides a property, sh:description, that would cover UCO's latter usage of rdfs:comment strings, with this prescription:

If present, tools SHOULD prefer those locally specified labels over globally specified labels at the rdf:Property itself.

UCO and its related ontologies should adopt the practice of using these specific strings.

Requirements

Requirement 1: For any rdfs:comment currently in a sh:PropertyShape used in UCO, it should be converted to a sh:description. Only one is known now.

Requirement 2: It must remain acceptable to store rdfs:comments in sh:PropertyShapes.

Further on requirement 2: Usage prescription of rdfs:comment should reduce to matters outside of user-level prescriptions, e.g. recording maintenance reminders.

Benefits

• Inlined documentation practice becomes more aligned with SHACL specification by using prescribed property, and semantics of UCO property shapes strengthens past usage of "Catch-all" documentation property rdfs:comment.
• Reviews of UCO's usage of SHACL can be better tested by using prescribed property.
• sh:description is intended for only use on sh:PropertyShapes, so a general query for natural-language descriptions of property-class associations can comfortably use only sh:description.
• Sets example for any writing "Downstream" SHACL shapes that further define constraints on UCO properties (such as due to organization-specific requirements that certain properties must be provided).

Risks

• Two unrelated documentation remarks that might be suited for storing as individual rdfs:comments would need to be stored in one sh:description string, per prescription ("should"-strength, not "must"-strength) that a sh:description "may have multiple values, but should only have one value per language tag." This is believed to be low risk, due to the prescription not being a firm "must"-level requirement.
• Review of UCO for documentation strings would need to be upgraded to look for both rdfs:comment and sh:description. This is believed to be low risk, as current UCO practice of using blank nodes for sh:PropertyShapes somewhat necessitates independent logic for reviewing documentation of sh:PropertyShapes instead of sh:NodeShapes.
• In case there was concern, UCO documentation generation is unaffected by changing sh:PropertyShape inlined documentation. In-property-shape documentation is currently not incorporated, though this would be a good feature to request.

Competencies demonstrated

Competency 1

Class-property associations can be reviewed.

The following query shows all of the class-property associations that are described with natural-language documentation in UCO:

SELECT ?lClassLabel ?lPropertyLabel ?lDescription
WHERE {
  ?nClass
    a owl:Class ;
    rdfs:label ?lClassLabel ;
    sh:property ?nPropertyShape ;
    .

  ?nPropertyShape
    rdfs:comment ?lDescription ;
    sh:path ?nProperty ;
    .

  ?lPropertyLabel
    rdfs:label ?lPropertyLabel ;
    .
}
ORDER BY ?lClassLabel ?lPropertyLabel ?lDescription

Run against UCO 0.7.0, this is the result of that query:

	?lClassLabel	?lPropertyLabel	?lDescription
0	FileFacet	sizeInBytes	When used to characterize a file the sizeInBytes property conveys the recorded size of a file in a file system.

The rdfs:comment used in that query can be replaced with sh:description after adoption of this proposal.

Solution summary

Requirement 1 also fully describes the solution, implemented in PR 358.

Coordination

• Tracking in Jira ticket OC-230
• Requirements to be discussed in Ontology Committee (OC) meeting, 2022-04-07

• Requirements Review vote occurred, passing, on 2022-04-07
• Requirements development phase completed.
• Solution announced to OCs on 2022-05-10
• Solutions Approval to be discussed in OC meeting, 2022-05-17
• Solutions Approval vote occurred, passing, on 2022-05-27
• Implementation merged into develop
• Milestone linked
• Documentation logged in pending release page