Also want to get feedback on the generation of SHACL for relationship types (related to https://github.com/spdx/spdx-3-model/pull/1293):
Currently, I parse the description of relationship type entries to generate a table of relationship types: https://openregtech.github.io/spdx-spec/v3.1-dev/model/Core/Vocabularies/RelationshipType/ This offers more readable relationship type information, as it continues to grow. The parser/generator (https://github.com/bact/specmd) relies on the mechanical language that we are trying to keep it consistent in the spec ("from"/"to"/"is constrained to" followed by class names). It is not totally reliable but can produce some working results (more discussion about this in 2nd half of this email). See the model artefacts it generates https://openregtech.github.io/spdx-spec/v3.1-dev/rdf/spdx-model.ttl https://openregtech.github.io/spdx-spec/v3.1-dev/rdf/spdx-context.jsonld https://openregtech.github.io/spdx-spec/v3.1-dev/rdf/schema.json (Search for "spdx-core:Relationship a owl:Class" in spdx-model.ttl to see the new SHACL for relationship types) -- As mentioned above, while current natural language parsing works considerably great, it can break silently, which is not good. And it may not work with plural form of class names in English. A more reliable way is to explicitly say what we like to see in SHACL. So the parser above can also take a proposed extended convention for our SPDX Markdown format (see below), to precisely control what we like to see in SHACL: ``` ## Entries - entryName: - description: A description of this entry. - from: SourceClass - to: - TargetClass - AnotherTargetClass - relationshipClass: ConstraintRelationship - sinceVersion: 2.0 - deprecated: true - deprecatedVersion: 2.1 - isReplacedBy: /Core/replacementEntry ``` The only mandatory field is "description". The rest are optional. ("from" and "to" have Element as default; "relationshipClass" has "Relationship" as default; more details in https://github.com/bact/specmd/blob/main/docs/format.md#structured-entry-format ) For example, currently we write: ``` ## Entries - affects: The `from` Vulnerability, Action or DefinedProcess affects each `to` Element. - amendedBy: The `from` Element is amended by each `to` Element. - doesNotAffect: The from Vulnerability has no impact on each to Element. The use of the doesNotAffect is constrained to VexNotAffectedVulnAssessmentRelationship classed relationships. ``` In the new format, we will write: ``` ## Entries - affects: - description: The `from` Vulnerability, Action or DefinedProcess affects each `to` Element. - from: - Vulnerability - Action - DefinedProcess - amendedBy: - description: The `from` Element is amended by each `to` Element. - doesNotAffect: - description: The `from` Vulnerability has no impact on each `to` Element. - from: Vulnerability - to: Element - relationshipClass: VexNotAffectedVulnAssessmentRelationship ``` Spec authors will write Markdown the same way with the same text editor. The parser will taking care of the conversion to SHACL. (There's also a migration path to convert current Markdown to the Markdown with this format. There's also a "main.py" script that can take all the same parameters like spec-parser, so existing CI won't break) -- Do you think this is useful? Or what it can be improved to be useful? regards, Art -=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#6200): https://lists.spdx.org/g/Spdx-tech/message/6200 Mute This Topic: https://lists.spdx.org/mt/120050653/21656 Group Owner: [email protected] Unsubscribe: https://lists.spdx.org/g/Spdx-tech/unsub [[email protected]] -=-=-=-=-=-=-=-=-=-=-=-
