RE: [sarif] Proposed design for screenshots: #137

After a spirited discussion in the issue, I’m going to propose this:

 

run

  =attachments:attachment[]

 

result

  =attachments:attachment[]

 

attachment

  =description:message

  =fileLocation

  +regions:region[]

  +rectangles:rectangle[]

 

region

  +message

 

+rectangle

  top:integer, left:integer, bottom:integer, right:integer

  message

 

An attachment now has an array of regions, and a region can now have a message. The user will usually experience region.message as hover text when the attachment is open in a SARIF viewer.

 

An attachment now also has an array of rectangles, each of which can also have a message. These rectangles can be used when the attachment is an image – any kind of image, not just a screenshot. The user will usually experience rectangle.message as hover text when the attachment is open in a SARIF viewer.

 

With this design, there is no need to add a separate screenshot object. There is also no need for the "screenshot" value for file.roles, so I’ll remove it.

 

Working on the change draft now.

 

Larry

 

From:  <> On Behalf Of Larry Golding (Comcast)
Sent: Monday, April 23, 2018 11:15 AM
To: 
Subject: RE: [sarif] Proposed design for screenshots: #137

 

I should have mentioned that the ability to annotate file regions in an attachment (attachment.annotations) is also new as part of this proposal. I’d been thinking about that one for so long that I forgot it was new 😊.

 

From:  <> On Behalf Of Larry Golding (Comcast)
Sent: Monday, April 23, 2018 11:10 AM
To: 
Subject: [sarif] Proposed design for screenshots: #137
Importance: High

 

TL;DR: We propose to support screenshots – and in fact, any type of image – by  adding an array of rectangle objects to the attachment object, and allowing any rectangle to have an associated message. This allows you to attach any image and annotate areas of interest in it.

 

Credit where it’s due: This is Michael’s proposal, simpler than what I originally suggested.

 

Using the same notation I’ve used in the past, the proposal is:

run
  =attachments:attachment[]

result
  =attachments:attachment[]

attachment
  =description:message
  =fileLocation
  +annotations:annotation[]
  +rectangles:rectangle[]

+rectangle
  top:integer, left:integer, bottom:integer, right:integer
  message

Since the ability to annotate an area is now part of attachment, there’s no need to define a screenshot object, and there’s no need to define a special screenshot “role” in file.roles.

 

Note the difference between attachment.annotations and attachment.rectangles: attachment.annotations allows you to associate a message with a region of a file; attachment.rectangles allows you to associate a message with an area in an image.

 

https://github.com/oasis-tcs/sarif-spec/issues/137

 

Larry