Define oslc:ResourceShapeConstraints

[berezovskyi]

During the call last Thu we decided to create oslc:ShapeCollection resource to add metadata to the shape file. For the backstory see #325 (comment) and https://github.com/oslc-op/oslc-admin/blob/master/minutes/2020/2020-06-25.md#shapes-metadata

---

• @berezovskyi Add a ShapeCollection resource to the vocab
• @berezovskyi Add a ShapeCollection instance to the QM spec shapes
• @berezovskyi Add a rdfs:isDefinedBy property on every QM shape
• @ndjc Add ShapeCollection checks to the ShapeChecker

[jamsden]

Are you proposing that this has to be done before Core PS01 and QM PS01 are published? If so, why? #325 indicated the metadata on ontologies was nice to have but should not hold up publication. Wouldn't it be the same for shapes.

This will required changes to ResourceShapes too.

[jamsden]

What will we not be able to do if this is deferred? Ensures the links for the vocab and shapes are properly aligned when published. See: https://github.com/oslc-op/oslc-specs/pull/325/files for proposed properties that would be the same on the ontology.

Optionally ShapeChecker would be able to check it.

We need to understand:

1. What problem are we trying too solve?
2. What are we proposing to do to solve it?
3. What is the impact on existing specifications?
4. Is it required for PS01?

[jamsden]

Attempting to make some progress on this in order to get Core and CM PS01 published, here's my proposed answers to the questions above:

1. What problem are we trying to solve? Ensuring we can version align published specs, vocabs, and shapes
2. What are we proposing to do to solve it? Add ResourceShapeConstraints
3. What is the impact on existing specifications? We don't define a ResourceShapeConstraints vocabulary term or shape for OSLC. Rather similar to Ontology in vocab files, we simply create an instance of it for the shapes documents to contain the metadata. So it only impacts the shapes.ttl file. Processing this metadata in ShapeChecker can come later.
4. Is it required for PS01? Nice to have.
5. What properties are we adding to Ontology and ResourceShapeConstraints?

dcterms:license <http://www.apache.org/licenses/LICENSE-2.0> ;
dcterms:relation <link to actual version of vocab or shape file in git repo> ;
# pdated every time the vocab or shape file is modified.
# Pull request reviewers shall reject a change without proper dcterms:modified entry
dcterms:modified "2020-06-04"^^<http://www.w3.org/2001/XMLSchema#date> ;
#   only to be used during the publishing process
#   dcterms:issued "2020-06-04"^^<http://www.w3.org/2001/XMLSchema#date> ;
dcterms:hasVersion "WD" ;
# TODO update before publishing; make sure to point to https://docs.oasis-open-projects.org/oslc-op/ URI
oslc_asset:tag rdf:nil ;
dcterms:isPartOf <link to corresponding OSLC specification> ;
dcterms:source <link to actual version of vocab or shape file in git repo> .

Questions:

• What is the difference between dcterms:releation and dcterms:source
• Do we really need dcterms:modified? Its available from the repo using the link and its probably the issued date and hasVersion that are needed to tie the documents together.
• What is oslc_asset:tag for? The GitHub release tag? Also seems redundant with issued and hasVersion.

[berezovskyi]

1. The problem we are trying to solve is to ensure provenance of the shapes and vocabs throughout their lifecycle after publication (incl. in archive, retrievals via conneg from open-services and downloaded files via Save As) to avoid cluster!@#% inconveniences like Wrong NS links website#265 from ever happening again.
2. The proposal is to: (a) add a metadata resource to the shapes much like the one already present in vocabs and (b) to ensure both metadata resources have properties that are uniquely updated on every publication of the spec so that there is a 1-1 mapping for every machine-readable file to the spec revision. See an example below. Whethere there is a specific RDF vocab class defined for it or not is not relevant (if there is, it MUST be defined in the vocab properly; without a specific vocab class it will be a bit difficult to check the shapes file with the shapechecker tool).
3. No impact.
4. Absolutely essential.
5. Agree with Jim's proposal.

http://open-services.net/ns/core/shapes/3.0/
    a rdf:Resource ;
    dcterms:license <http://www.apache.org/licenses/LICENSE-2.0> ;
    dcterms:relation <link to actual version of vocab or shape file in git repo> ;
    # pdated every time the vocab or shape file is modified.
    # Pull request reviewers shall reject a change without proper dcterms:modified entry
    dcterms:modified "2020-06-04"^^<http://www.w3.org/2001/XMLSchema#date> ;
    #   only to be used during the publishing process
    #   dcterms:issued "2020-06-04"^^<http://www.w3.org/2001/XMLSchema#date> ;
    dcterms:hasVersion "WD" ;
    # TODO update before publishing; make sure to point to https://docs.oasis-open-projects.org/oslc-op/ URI
    oslc_asset:tag rdf:nil ;
    dcterms:isPartOf <link to corresponding OSLC specification> ;
    dcterms:source <link to actual version of vocab or shape file in git repo> .

[jamsden]

I specifically propose something like this would be added to every shape .ttl file

http://open-services.net/ns/core/shapes/3.0/
    a oslc:ResourceShapeConstraints ;
    dcterms:license <http://www.apache.org/licenses/LICENSE-2.0> ;
    #   Updated when a new revision is published
    #   dcterms:issued "2020-06-04"^^<http://www.w3.org/2001/XMLSchema#date> ;
    dcterms:hasVersion "WD" ;
    dcterms:isPartOf <link to corresponding OSLC specification> ;
    dcterms:source <link to actual version of vocab or shape file in git repo> .

Similar metadata properties would also be added to the vocab files.

[berezovskyi]

Thanks @jamsden! Let's end here and adopt your proposal unless @jadelkhoury or @ndjc or @DavidJHoney have any objections.

[berezovskyi]

Just talked to Jim, his proposal did not imply removing any predicates already used in vocab metadata except for the modified date. Final set of properties:

http://open-services.net/ns/core/shapes/3.0/
    a oslc:ResourceShapeConstraints ; # or owl:Ontology
    dcterms:title "OSLC Core Resource Shape Constraints" ; # or "OSLC Core Vocabulary"
    rdfs:label "Core Resource Shape Constraints" ; # or "OSLC Core Vocabulary"
    vann:preferredNamespacePrefix "oslc_shapes" ; # or "oslc"
    dcterms:description "Resource Shape Constraints defined in the OSLC Core 3.0 specification."^^rdf:XMLLiteral ;
    dcterms:publisher <https://open-services.net/about/> ;
    dcterms:license <http://www.apache.org/licenses/LICENSE-2.0> ;
    # TODO add dcterms:issued property when published, same as in ReSpec
    # dcterms:issued "2020-XX-XX"^^<http://www.w3.org/2001/XMLSchema#date> ;
	# TODO change to the file under https://docs.oasis-open-projects.org/oslc-op/
    dcterms:source <https://github.com/oslc-op/oslc-specs/blob/master/specs/core/core-vocab.ttl> ;
	# TODO change to the file under https://docs.oasis-open-projects.org/oslc-op/
    dcterms:isPartOf <https://oslc-op.github.io/oslc-specs/specs/core/oslc-core.html> ;
	# TODO change to the STAGE##
    dcterms:hasVersion "WD" .

[berezovskyi]

Took a first stab at it in #367

[ndjc]

In my recent PR, ShapeChecker has been updated to allow (but not require) these properties on the base resource in a shapes file. No rdf:type property on that subject is permitted.

[ndjc]

Following last week's meeting, I have changed ShapeChecker to use the oslc:ResourceShapeConstraints resource - my previous comment is no longer valid. This resource should be closed once at least one spec has been merged to master with this new resource, and the result passes ShapeChecker with its new -C flag.

[berezovskyi]

With the oslc:ResourceShapeConstraints being added to the QM spec in #367 and to the SC tool in #371, I am closing this issue. Please reopen if the resolution is wrong, but file new issues to get add the metadata in other specs.