The change draft is:
https://github.com/oasis-tcs/sarif-spec/blob/master/Documents/ChangeDrafts/Accepted/sarif-v2.0-issue-376-kupsch-additional-feedback-2.docx
Larry
From:
Larry Golding (Myriad Consulting Inc)
Sent: Thursday, April 25, 2019 11:50 AM
To: James Kupsch <>;
Subject: RE: comments on draft with no action
Inline
Thank you again, Jim, for the valuable feedback!
Larry
From:
James Kupsch <
>
Sent: Tuesday, April 16, 2019 12:49 PM
To: Larry Golding (Myriad Consulting Inc) < >;
Subject: Re: comments on draft with no action
Larry,
Sorry I didn't see the comments earlier. I didn't scroll far enough before looking at the change draft and the github issue and didn't see that there was comments on the items not updated in the document.
My comments on some of the items are below in red.
Jim
On 4/15/19 4:31 PM, Larry Golding (Myriad Consulting Inc) wrote:
Hi Jim,
With the exception of "location relationships" which we're still considering, the items you list below are the ones we decided not to take. I sent you an email with responses on all your items, including rationales for the ones we did not take. I've attached it here to share it with everybody. I suppose I should fill out #366 with the rest of the responses.
Thanks,
Larry
The following suggestion was rendered moot by the changes we accepted:
Appendix D no longer uses the lack of a converter version number to justify the now-removed advice against synthesizing properties, so the text that incorrectly stated that a converter doesn t have
a version number has been removed.
We could discuss whether the general guidance for version numbers on tool components should be changed. As the spec stands, all the versioning properties
MAY be present. I d be open to tightening that, for instance, At least one of version or semanticVersion
SHOULD be present.
This would be reasonable statement to add about the versions.
[Larry] Done:
3.19.2 Constraints
At least one of
version
( 3.19.10) and
semanticVersion
( 3.19.9)
SHOULD be present.
Here are explanations on some of your other feedback items:
With regard to your question about the distinction between
toolComponent.productSuite , product , and
name , think Microsoft Office/Excel/Excel Charting Tool .
It would be useful to state that name is intended to be displayed to users as the tool's name
[Larry] Given the name of the property ("name") and the fact that it s a localizable string, I think that is sufficiently clear as the spec stands.
and that viewers may display this as part of a table the name should be short; ideally it should not include line breaking characters, the company name, version information, product or productSuite that are available
in other properties.
[Larry] Given the existence of the corresponding property "fullName", the contrast in the examples between them, and the new section on product hierarchy properties (see below), I don t think this is necessary.
Move the product and productSuite section to immediately follow the name section as they are similar concepts.
[Larry] Done
In the product and productSuite properties state that these can be used to form a hierarchy of related software: name can be part of a product which can be part of a productSuite.
[Larry] Done:
3.19.7 Product hierarchy properties
The
name
( 3.19.8) or
fullName
( 3.19.9),
product
( 3.19.10), and
productSuite
( 3.19.11) properties establish a hierarchy of related software: the tool component
identified by
name
and/or
fullName
is part of the product named by
product , which in turn is part of the product suite identified by
productSuite .
With regard to your suggestion to provide a short (20-30 character) human readable name for a
reportingDescriptor that is localizable and not necessarily stable, we do have such a property:
reportingDescriptor.name . See 3.46.7 in the provisional draft ( 3.44.7 in the e-ballot-3 draft). We don t provide explicit guidance on its length, but the example given ( "SpecifyMarshalingForPInvokeStringArguments" )
conveys the idea.
There should be advice similar to the above section. Viewer should use the name of the descriptor (or the id in its absence) to label this type of issue to users. The name should be short as it may be displayed
in tabular views that have limited horizontal space. It should not include line breaking characters.
[Larry] I think the example is sufficiently clear, and given the spec says that this is
a localizable string ( 3.5.1) containing an identifier that is understandable to an end user
I don t think I need to tell a viewer that it can display it as an issue label.
With regard to your suggestion in 3.15.2 ( externalPropertyFileReference.location ) that we not restrict
uriBaseId , this section does not actually introduce a new restriction. 3.4.4 ( artifactLocation.uriBaseId property) already says:
If the
uri
property contains an absolute URI, the
uriBaseId
property SHALL be absent.
Although strictly speaking there s no need to repeat that in 3.15.2, I think it s helpful, so I added
these words :
If
location
is present, its
uri
property SHALL be an absolute URI using the
sarif
scheme ( 3.10.3), and
so (by 3.4.4) its
uriBaseId
property
SHALL be absent.
My point here was that this text says that if you are using a sarif scheme URI, then the location SHALL NOT include a uriBaseId. I think that the uriBaseId should be allowed. It seems perfectly reasonable to create
a baseUriId named INLINED that has a uri="sarif:/inlineExternalProperties", and to then have a location of {uriBaseId="INLINED", uri="0"}. To support this, the text should just say that the resolved location SHALL be an absolute URI with a sarif scheme.
[Larry] Agreed:
If
location
is present, its
uri
property
SHALL
resolve to an absolute URI using the
sarif
scheme ( 3.10.3).
For the following suggestion,
we have two proposals:
Add more languages . We don t want to be in the business of proposing an exhaustive list, or even of presenting a list that spans many pages. Here are two
options:
a) In the Appendix, add a statement to the effect that this list is just a start, and we expect the community to develop it over time.
b) Remove the Appendix.
I would add just a couple of more languages to cover more of the languages in the top-n lists (if you add these and format as 2-columns it will fit on one page).
visualbasic
visualbasicdotnet
objectpascal
r
d
groovy
lisp
lua
prolog
scheme
ada
rust
julia
haskell
erlang
actionscript
clojure
ocaml
[Larry] Done
We decided not to take the following suggestions:
With regard to the suggestion to introduce toolComponent.abbreviatedName , we prefer to add guidance to the effect that the tool name should be narrow because you never know where it s going to be displayed, and if the
name is long, at least make sure that its leading portion is sufficiently informative to survive the name being truncated.
Adding guidance would be useful for the tool name and descriptor names would be useful. There is commentary in 11 and 12 above.
[Larry] Not done.
With regard to the guidance around toolComponent.shortDescription and
fullDescription : We understand that converters can t always follow the guidance; converters are always at the mercy of the native output format. And a tool author who writes in a language with no sentences, or who writes
a message whose first sentence can t be readily identified, should follow the guidance and supply both short and full descriptions.
Unless a first sentence algorithm can be defined, then viewers can not follow this document. It would be better to just say that if the shortDescription is not present, viewers MAY displays a truncated version of
the fullDescription such as the first 100 characters, the first paragraph, or the first sentence. This description is something that a viewer can easily do and gives the viewer latitude in how to truncate the text.
[Larry] Done:
The
beginning of
fullDescription
( for example, its first sentence )
SHOULD provide a concise description of the tool component, suitable for display in cases where available space is limited. Tools that construct
fullDescription
in this way do not need to provide a value for
shortDescription
( 3.19.17). Tools that do not construct
fullDescription
in this way
SHOULD provide a value for
shortDescription .
NOTE: The rationale for this guidance is that in the absence of
shortDescription , a viewer with limited display space might display a truncated version of
fullDescription , for example, the first sentence (if a sentence is identifiable), the first paragraph, or the first 100 characters. If this guidance is not followed, that truncated description might not be understandable.
Likewise for toolComponent.shortDescription and
fullDescription .
[Larry] I assume you meant reportingDescriptor on this one (or maybe I made a mistake transcribing your feedback). In any case, Done on reportingDescriptor as well.
Likewise for the guidance in 3.11.3 about plain text messages (we did take the suggestion to remove the restriction to a single paragraph).
[Larry] I removed the requirement for complete sentences since so many plain text messages occur in context where only a fragment or a few words is needed. Interestingly, we never had corresponding guidance on Markdown
messages.
