jamsden commented 3 months ago

[x] The oslc_sysmlv2:Element rdfs:subClassOf oslc_am:Resource is missing.

[x] The SysML ResourceShapes are missing the inherited oslc_am:Resource properties. The following oslc_am properties need to be copied into sysml-shapes.ttl, it is not possible to inherit, or reference "inherited" shape properties.

oslc:property 
    :type,
    :dctype,
    :identifier,
    :title,
    :shortTitle,
    :description,
    :source,
    :creator,
    :contributor,
    :created,
    :modified,
    :serviceProvider,
    :instanceShape,

    # Common link types
    :derives,
    :elaborates,
    :refine,
    :external,
    :satisfy,
    :trace,

Since ResourceShapes do not support inheritance, the oslc_am:Resource properties will need to be replicated in every oslc_sysmlv2 class, making the sysml-shapes.html file huge. But this can be done. It should be part of the sysml-shapes.ttl generation from SysML/20240201/SysML.xmi.

[x] The sysml-shapes.ttl file should uses a default namespace of:
```
@prefix : < http://www.omg.org/spec/SysML/20240801/vocab#> .
```

: a oslc:ResourceShapeConstraints ; dcterms:title "OSLC System Modeling Language (SysML) Version 2.0 Constraints" ; rdfs:label "OSLC System Modeling Language (SysML) Constraints" ; dcterms:description "All vocabulary URIs defined in the OSLC System Modeling Language (SysML) namespace."^^rdf:XMLLiteral ; dcterms:publisher https://open-services.net/about/ ; dcterms:issued "2024-08-01"^^http://www.w3.org/2001/XMLSchema#date ; dcterms:license http://www.apache.org/licenses/LICENSE-2.0 ; dcterms:source https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-shapes.ttl ; dcterms:isPartOf https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-spec.html ; dcterms:hasVersion "PSD" ; dcterms:dateCopyrighted "2012-2024" .


- [x] The Turtle files need the copyright and license comments added

Copyright 2024 OASIS Open

#

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

#

http://www.apache.org/licenses/LICENSE-2.0

#

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.


- [x] The vocab file needs to define an oslc-sysmlv2 ontology 

- [x] The vocab file needs to include classes for enumerations and enumeration literals 

- [x] The vocabulary terms need to rdfs:subClassOf their supertypes

@prefix oslc_sysmlv2: https://www.omg.org/spec/SysML/2.0#

oslc_sysmlv2: a owl:Ontology ; dcterms:title "OSLC SysML v2 Vocabulary" ; rdfs:label "OSLC SysML v2 Vocabulary" ; dcterms:description "All vocabulary URIs defined in the OSLC SysML v2 namespace."^^rdf:XMLLiteral ; vann:preferredNamespacePrefix "oslc_sysmlv2" ; dcterms:publisher https://open-services.net/about/ ; dcterms:issued "2022-07-11"^^http://www.w3.org/2001/XMLSchema#date ; dcterms:license http://www.apache.org/licenses/LICENSE-2.0 ; dcterms:source https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/os/sysml-vocab.ttl ; dcterms:isPartOf https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/os/sysml-spec.html ; dcterms:hasVersion "WD" ; dcterms:dateCopyrighted "2012-2024" .


- [x] All rdf:Property and rdfs:Class elements should have:

rdfs:isDefinedBy oslc_sysmlv2: ; rdfs:label "{name}" ;


- [x] Turtle files should be generated, not RDF/XML

- [x] The Turtle files should include `@prefix oslc_sysmlv2: <https://www.omg.org/spec/SysML/2.0#> `. And use it to shorten the class and property definitions. The shapes file requires this to render properly.

- [x] The rdfs:comments cannot include HTML markup, ReSpec does not render markup in the vocab document.

The [rdfs:domain](https://www.w3.org/TR/rdf-schema/#ch_domain) of rdfs:comment is [rdfs:Resource](https://www.w3.org/TR/rdf-schema/#ch_resource). The [rdfs:range](https://www.w3.org/TR/rdf-schema/#ch_range) of rdfs:comment is [rdfs:Literal](https://www.w3.org/TR/rdf-schema/#ch_literal). So these should not contain markup and should not be rendered/formatted. They are simple text stings.  

Markup should be stripped from these refs:comment assertions, and be shortened to only the first paragraph.

Note that the dcterms:description property of a ResourceShape is an XMLLiteral and can, and often does include markup.

- [x] Some of the dcterms:descriptions which are XMLLiterals in sysml-shapes.ttl are really long and don't render properly in the sysml-shapes.html. We should consider shortening, maybe using the first sentence or paragraph. 

- [x] The SysML vocab and shapes files result in a large number of shapeChecker errors.

A prerequisite to publishing a PS01 is to address all shapeChecker errors

cd ~/Developer/OSLC/oslc-op/oslc-specs/tools/ShapeChecker build/install/ShapeChecker/bin/ShapeChecker \ -v ../../specs/sysml/sysml-vocab.ttl \ -s ../../specs/sysml/sysml-shapes.ttl



Categories of shapeChecker errors:
    Markup in XMLLiteral for rdfs:comment generates a lot of warnings
    Warning on https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/os/sysml-spec.html: This resource is not fetchable. (bad value 404)
    Warning on http://open-services.net/ns/sysmlv2#portConjugationOriginalPortDefinition: This subject does not appear to be part of an ontology or one of its terms. (bad value http://www.w3.org/1999/02/22-rdf-syntax-ns#type)
       While examining resource shape http://open-services.net/ns/sysmlv2#SatisfyRequirementUsageShape:
          Warning on http://open-services.net/ns/core#name: This property is unexpected. (bad value SatisfyRequirementUsageShape)
          Warning on http://purl.org/dc/terms/description: The XML literal is not well-formed. (bad value <p>A <code>SatisfyRequirementUsage</code> is an <code>AssertConstraintUsage</code> that asserts, by default, that a satisfied <code>RequirementUsage</code> is true for a specific <code>satisfyingFeature</code>, or, if <code>isNegated = true</code>, that the <code>RequirementUsage</code> is false. The satisfied <code>RequirementUsage</code> is related to the <code>SatisfyRequirementUsage</code> by a <code>ReferenceSubsetting</code> <code>Relationship</code>
    Warning on http://purl.org/dc/terms/description: The description or comment should end with a period (full stop).

- [ ] KerML vocab and shapes files need to be generated too.

jamsden commented 3 months ago

Jad, See Resources/getclasses.ipynb - a Jupyter notebook that gets the first paragraph and strips the HTML for the rdfs:comment in the vocab, and just gets the first paragraph and keeps the HTML markup for the dcterms:description in the shapes file.

This looks like the result is just fine. So I think this is a reasonable approach - using the first paragraph.

jamsden commented 3 months ago

Also adding rdfs:isDefinedBy oslc_sysmlv2: and fixing the rdfs:comment cleaned up most of the shapeChecker errors. So we're on the right track.

jamsden commented 3 months ago

I've updated the files in the repo, so you can see what I patched up so far.

jamsden commented 3 months ago

Jad, if you can't get the .ttl files regenerated and cleaned up before next week, then I propose we consider publishing what we have now as PSD01.

Jad-el-khoury commented 3 months ago

@jamsden! I am on easter break this week. Will try to get started, but the list is extensive. A good approach would be that we publish what you are manually making, and this gives me time to catch up.

jamsden commented 3 months ago

Ok, I'll prepare the documents for publishing PSD01 using what I have. We can fix it in a subsequent revision or PS.

jamsden commented 3 weeks ago

This has been re-implemented and the items above completed, so closing.

oslc-op / oslc-specs

The SysML vocab and shapes generated from SysML/20230201/SysML.xmi need some updates #614

Copyright 2024 OASIS Open

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.