Change draft for #162 (namespaced run.automationId)

["Larry Golding \(Comcast\)" <larrygolding@comcast.net>]

I pushed a change draft for Issue #162, “run.automationId is namespaced”.

 

Documents/ChangeDrafts/Active/sarif-v2.0-issue-162-namespaced-automationId.docx

 

I’ll move its adoption at TC #17 on May 16^th.

 

This is one of those changes where it’s all in the preparation. I first DRY’d out the existing two uses of “namespaces” by introducing §3.4.3, “Namespaced string properties”:

3.4.3 Namespaced string properties

Certain string-valued properties in this specification (for example run.automationId (§3.11.5) and the elements of a property bag’s tags array (§3.7.2)) are said to be “namespaced”. This means that the property value consists of a sequence of forward-slash-separated components, with this syntax:

namespaced string = component, { "/", component };

 

component = component character, { component character };

 

component character = ? JSON string character ? - "/";

For examples, see §3.7.2 and §3.11.5.

The description of every namespaced property will state that it is namespaced.

A SARIF consumer SHALL interpret the values of a namespaced string as forming a logical hierarchy.

NOTE: A namespaced value does not need to include any forward slashes. The syntax permits a single string of non-forward-slash characters. The purpose of this section is to define the semantics of the forward slash character in those properties that respect it.

In string-valued properties that are not described as namespaced, the forward slash character has no special meaning, and a SARIF consumer SHALL NOT interpret it as dividing the value into hierarchical components.

 

Then I modified the existing uses of namespacing to refer to this section (see the change draft).

 

The change that actually addresses this issue is then one sentence (although I took the opportunity to improve the example):

3.11.5 automationId property

A run object MAY contain a property named automationId whose value is a string containing an identifier that allows the run to be correlated with other artifacts produced by a larger automation process.

The automationId property is namespaced (§3.4.3).

EXAMPLE 1: In an environment where an analysis tool is executed as part of an automated build process, the “build id” assigned by the build system might serve as the automationId, allowing the tool run to be associated with other artifacts produced by the build. Again depending on the environment, automationId might take advantage of namespacing and include the name of the build queue.

{

  "automationId": "Nightly/14.0.1.02",

  ...

 

Larry