RE: [oslc-domains] Feedback for RM spec

["Sarabura, Martin" <msarabura@ptc.com>]

Thanks Nick, yes that works perfectly. So I have some additional comments re the vocab file:

 

1. Sec 2: What does **root** mean here? This specification defines the **root** superclass, and a number of specific, commonly occurring subclasses, properties and values. Servers may define additional **root** subclasses and provide additional properties as needed.
2. Shouldn’t we have a non-normative recommendation for how to represent a tree structure in these collections? The only real option available here is the oslc_rm:uses property. Presumably it can include another requirements collection; thus creating a hierarchy. Since it is the only option then presumably everybody will figure that out but it’s such a common scenario (ReqIF, Integrity LM) that it seems worth mentioning – or some other approach if oslc_rm:uses is not desirable for some reason.
3. Another philosophical question, what is the granularity of Requirements Collections in relation to Service Provider (or LDPC)? I can see them being identical, or, it could be that there are many requirements collections within a given service provider. What would be our (presumably non-normative) recommendation for how to design this?
4. I believe we need to state that you must not use OSLC namespaces for non-OSLC properties, right? Thus change the sentence: It is strongly recommended that any additional properties be defined in XML namespaces distinct from those defined by OSLC in these specifications. I need to find that reference in the Core docs
5. dcterms:modified – Timestamp last latest resource modification

 

Regards, Martin

 

Dr. Martin Sarabura
Technical Fellow, Office of Research & Architecture

+1 519.502.4819
msarabura@ptc.com

 

 

 

 

 

From: oslc-domains@lists.oasis-open.org [mailto:oslc-domains@lists.oasis-open.org] On Behalf Of Nicholas Crossley
Sent: Thursday, March 01, 2018 6:23 PM
To: Jim Amsden <jamsden@us.ibm.com>
Cc: oslc-domains@lists.oasis-open.org
Subject: Re: [oslc-domains] Feedback for RM spec

 

The following URL works better than htmlpreview.github.io:

https://rawgit.com/oasis-tcs/oslc-domains/master/rm/requirements-management-vocab.html

Nick.



From:        "Jim Amsden" <jamsden@us.ibm.com>
To:        "oslc-domains@lists.oasis-open.org" <oslc-domains@lists.oasis-open.org>
Date:        03/01/2018 01:18 PM
Subject:        Re: [oslc-domains] Feedback for RM spec
Sent by:        <oslc-domains@lists.oasis-open.org>

---

Martin,
Thanks for the thorough review. Re vocab and shape, looks like ReSpec is having difficulty with the github URLs. You may need to git checkout and review on your local machine. I do that anyway for editing purposes.


Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:        "Sarabura, Martin" <msarabura@ptc.com>
To:        "oslc-domains@lists.oasis-open.org" <oslc-domains@lists.oasis-open.org>
Date:        03/01/2018 02:41 PM
Subject:        [oslc-domains] Feedback for RM spec
Sent by:        <oslc-domains@lists.oasis-open.org>

---

Hi all, I had a careful read through the RM spec. Could somebody please fix the vocabulary respect errors? The .ttl files are not being loaded. The rest of my comments are here.

Specification:

1. Additional artifacts references vocabulary 2.0 whereas the document itself says the version is 2.1 (https://htmlpreview.github.io/?https://raw.githubusercontent.com/oasis-tcs/oslc-domains/master/rm/requirements-management-vocab.html)

2. Abstract: <missing!>

3. Status: RF on Limited Terms hyperlink should be https://www.oasis-open.org/policies-guidelines/ipr#s10.2.3

4. Copyright notice should be 2018

5. Sec 1 2^nd sentence: supports key RESTful web services interface[s] for … (add [s])

6. Sec 1 3^rd sentence: OSLC [RM] takes an open…. (remove [RM])

7. Sec 1 4^th sentence: … were created by the OSLC Domains TC.

8. Recommend we move 1.4 (conventions and keywords) up to 1.2 so it applies to the rest of the document

9. I don’t think we need to include the IPR Policy section since the same text already appears in the Status section.

10. Should we have a Motivation section? See https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/config/oslc-config-mgt.html#motivationfor an example

11. Terminology section should be marked Non-normative and maybe use same formatting as in https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/config/oslc-config-mgt.html#terminology?

12. Sec 2.4 resource formats: Just a thought: Should we maybe have a reference to the exact document in which the normative requirements for core are listed? Specifically https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/oslc-core.html#resourceOperationswhere in 4.4.1 we say the service MUST accept text/turtle and application/ld+json. That’s pretty important!

13. Sec 2.5 authentication: In addition to … , OSLC [RM] servers SHOULD support… (not [CM])

14. Sec 2.6 – Same RM not CM

15. Sec 2.8.3 – Same RM not CM

16. Sec 3 – should be 2.1 not 2.0

17. Sec 4.1 – “outwith”? With all due respect to Ian, I’d recommend “beyond” as more standard English (2 instances)

18. Sec 4.3 – results misspelled “resutls”

 
Vocabulary:

1. Use a more current date under the title?

2. Additional artifacts should list Vocabulary as (this document)

3. Same notes re status, copyright notice

4. Move 1.3 up to 1.1?

5. Sec 1.3 references oslc_qm which I believe is not used in the rm spec? (Couldn’t find it in the vocab or shapes docs)

6. Sec 3.1 and 3.2: It is strongly recommended that any additional properties be defined in XML namespaces distinct from those defined by OSLC in these specifications. I believe the core spec says you MUST use non-OSLC namespaces.

7. Missing the actual vocabulary! 3 respec errors:

Error including URI=./requirements-management-vocab.ttl: error (NetworkError: Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'https://raw.githubusercontent.com/oasis-tcs/oslc-domains/master/rm/requirements-management-vocab.ttl'.)
Error including URI=./requirements-management-shapes.ttl#Requirement: error (NetworkError: Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'https://raw.githubusercontent.com/oasis-tcs/oslc-domains/master/rm/requirements-management-shapes.ttl'.)
Error including URI=./requirements-management-shapes.ttl#RequirementCollection: error (NetworkError: Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'https://raw.githubusercontent.com/oasis-tcs/oslc-domains/master/rm/requirements-management-shapes.ttl'.)

This is when I use https://htmlpreview.github.io/?https://raw.githubusercontent.com/oasis-tcs/oslc-domains/master/rm/requirements-management-vocab.html
To read the vocab spec. Should I use a different URL instead?

Regards, Martin

Dr. Martin Sarabura
Technical Fellow, Office of Research & Architecture

+1 519.502.4819
msarabura@ptc.com