Editorial: Clarify case where result.message contains only arguments

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

At editorial discretion, I added a passage to the description of result.ruleMessageId to clarify a point that confused a Microsoft engineer a couple of days ago.

 

He had a result with a ruleMessageId property that identified a message string in the rule metadata. That message string had a replacement sequence "{0}", and his question was where to put the replacement value. He thought it might be in result.message.arguments (and he was right), but he was confused because result.message is optional if ruleMessageId is present. Well, so it is, but that’s the only place to put the arguments, and you end up with a message object that contains nothing but arguments. NTTAWWT.

 

The change draft is at Documents/ChangeDrafts/Accepted/sarif-v2.0-editorial-message-arguments-only.docx. I merged it into the provisional draft.

 

Here’s the new passage:

 

If the message string identified by ruleId and ruleMessageId includes placeholders (§3.9.4), the replacement values for the placeholders SHALL be held in the result object’s message property (§3.19.6), in that message object’s arguments property (§3.9.11). In this situation, result.message will contain only the arguments property.

EXAMPLE 2: In this example, the message string identified by ruleId and ruleMessageId has a single placeholder "{0}". The replacement value "counter" is held in message.arguments.

{                                # A run object (§3.11).

  "results": [

    {                            # A result object (§3.19).

      "ruleId": "CA2101",

      "ruleMessageId": "default",

      "message": {

        "arguments": [

          "counter"

        ]

      }

    }

  ],

 

  "resources": {

    "rules": {

      "CA2101": {                # A rule object

        "messageStrings": {

          "default": "Variable \"{0}\" is uninitialized."

        }

      }

    }

  }

}

 

Larry