EBALLOT PROPOSAL. Define a reporting descriptor reference object that allows notifications to point into reporting metadata that may be persisted to the driver or any of its extensions or to the new taxonomies metadata.
API IMPACT
Schema only PR: Microsoft/sarif-sdk#1316
Create a reportingDescriptorReference type with these properties.
id of type string: a notification identifier
pointer of type string: a JSON pointer that locates the descriptor for the notification with that identifier.
In the reportingConfigurationOverride object:
Remove the notificationIndex, ruleIndex, and extensionIndex properties.
Replace them with a reportingDescriptorReference property of type reportingDescriptorReference, which specifies the reportingDescriptor whose configuration is being overridden.
In the notification object:
Remove the id property.
Replace it with a notificationDescriptorReference property of type reportingDescriptorReference.
Remove the ruleId and ruleIndex properties.
Replace them with an associatedRuleDescriptorReference property of type reportingDescriptorReference, which locates the descriptor for the rule, if any, with which this notification is associated.
In the invocation object:
Replace the property reportingConfigurationOverrides (which was defined to hold overrides for both rules and notifications) with separate properties ruleConfigurationOverrides and notificationConfigurationOverrides.
In the result object
Remove the ruleIndex and extensionIndex properties.
Replace them with a rulePointer property of type string, containing a JSON pointer that locates the rule descriptor.
EXAMPLE
{ # A run object
"tool": {
"driver": {
"name": "CodeScanner",
"ruleDescriptors": [
{ # A reportingDescriptor object.
"id": "CA2101",
"name": "DoNotBeEvil",
"shortDescription": {
"text": "Do unto others as you would have them do unto you."
},
"messageStrings": {
"default": {
"text": "Evildoing was detected."
}
},
"defaultConfiguration": {
"level": "error"
}
}
],
"notificationDescriptors": [
{
"id": "MSG0001",
"name": "RuleDisabled",
"shortDescription": {
"text": "This notification occurs when a rule is disabled due to an exception."
},
"messageStrings": {
"default": {
"text": "Rule {0} has been disabled."
}
}
}
]
}
},
"results": [
{ # A result object.
"id": "CA2101",
"rulePointer": "0" # In this context, an abbreviation for "driver/ruleDescriptors/0"
"message": {
"messageId": "default"
}
}
],
"invocations": [
{
"ruleConfigurationOverrides": [
{
"reportingDescriptorReference": {
"id": "CA2101"
"pointer": "0" # In this context, ruleDescriptors are the default target
},
"configuration": {
"level": "warning"
}
}
],
"toolNotifications": [ # toolExecutionNotifications if #330 is approved
{
"notificationDescriptorReference": {
"id": "MSG0001",
"pointer": "0" # In this context, an abbreviation for "driver/notificationDescriptors/0"
},
"associatedRuleDescriptorReference": {
"id": "CA2101",
"pointer": "0" # In this context, an abbreviation for "driver/ruleDescriptors/0"
}
"message": {
"messageId": "default",
"arguments": [
"CA2101"
]
}
}
]
}
]
}
NOTES
Certain JSON pointer-valued properties can be abbreviated, to optimize the most common cases:
A JSON pointer that refers to a descriptor defined by the tool's driver can be abbreviated to a stringified integer value >=0 that will be treated as a relative reference into the driver's ruleDescriptors array or notificationDescriptors array, as appropriate. That is, if notification.notificationDescriptorReference is "driver/notificationDescriptors/42", it can be abbreviated to "42", and if notification.associatedRuleDescriptorReference is "driver/ruleDescriptors/54", it can be abbreviated to "54".
We do not replace result.ruleId and result.rulePointer with a reportingDescriptorReference in order to minimize churn in SARIF pre-release v2 producers.
taxonomies will also use this mechanism. That is covered in #314.
https://github.com/oasis-tcs/sarif-spec/issues/324 |
