I pushed a change draft for
Issue #256, “Make run.files an array.”:
Documents/ChangeDrafts/Active/sarif-v2.0-issue-256-results-array.docx
We will move its adoption at TC #27 on Wednesday November 14th.
This is a very intrusive change and I urge you to read the change draft carefully. It is also a really good design improvement and simplification of the spec: it removes literally
pages of careful description and examples of how to construct the dictionary keys for the properties that are now arrays. The spec as a whole is only two pages shorter (147
vs 149 pages), mostly because I added content to the “Comprehensive SARIF file” in Appendix I.
I suggest that as you read this draft, you alternate between “Simple Markup” and “Full Markup” viewing modes. Simple Markup will give you a readable version, which Full Markup will allow you to see how much text was removed.
The changes include:
- In the
run object:
- Make the
files property an array.
- Remove the explanation of how to synthesize the property names.
run.files no longer has property names.
- Remove the explanation of how to synthesize URIs for nested files. Such URIs no longer need to appear as property names, and they actually never did need to appear as property values.
See the example in §3.20.2, “run.fileLocation property.”
Michael: I expect you’ll be curious about this. I can explain the reasoning offline, or in the TC meeting.
- Make the
logicalLocations property an array.
- Remove the description of how to synthesize the property names.
run.logicalLocations no longer has property names.
- In the
resources object:
- Make the
rules property an array.
- Remove the explanation of how to synthesize the property names.
resources.rules no longer has property names.
- In the
fileLocation object:
- Add an integer-valued
fileIndex property.
- Remove the explanation of how to synthesize an absolute
uri property for a nested file. It’s never necessary to do that. Again, see the example in §3.20.2, “run.fileLocation property.”
Michael: This is related to my note to you above. Again, I can explain offline or in the meeting. - Remove the constraint that the
uriBaseId property can’t include a
"#" character. That constraint was only there to avoid an ambiguity in interpreting property names in
run.files, but run.files doesn’t have property names any more.
- State the
uriBaseId cannot appear for nested files. Once again, the example in §3.20.2 shows the expected usage.
Michael: Again, this is related to my note to you above. Again, I can explain offline or in the meeting.
- In the
result object:
- Add an integer-valued
ruleIndex property.
- In the
notification object:
- Add an integer-valued
ruleIndex property.
- In the
location object:
- Add an integer-valued
logicalLocationIndex property.
- In the
file object:
- Replace the string-valued
parentKey property with an integer-valued
parentIndex property. This is the mechanism for associating a nested file with its parent file.
- Make the
fileLocation property required for top-level files. You used to be able to omit it if its
uri property matched the property name in
run.files.
- In the
logicalLocation object:
- Replace the string-valued
parentKey property with an integer-valued
parentIndex property. This is the mechanism for associating a nested logical location with its parent.
- Make the
name property required. You used to be able to omit it if it matched the property name in
run.logicalLocations.
- In the
rule object:
- Make the
id property required. You used to be able to omit it if it matched the property name in
resources.rules.
- Explain the trade-offs between specifying
uri or
fileIndex in fileLocation objects, and similarly, the trade-off between specifying
fullyQualifiedLogicalName or
logicalLocationIndex in location objects.
- In the section on externalizable properties, note that
run.files and
run.logicalLocations are now arrays.
- Modify the guidance in Appendix G on “Diagnosing results in generated files”.
- Modify all the examples in Appendix I, including fleshing out run.files in the Comprehensive example.
- Fix up all examples that include
run.files,
run.logicalLocations, or run.resources.rules.
That’s it! Happy reading.
Larry