RE: external vs fragment redux

["Larry Golding (Myriad Consulting Inc)" <v-lgold@microsoft.com>]

Per the spec, the top-level element of an external file is an object of type externalizedProperty. So how about file extension “.sarif-externalized-property”? (Or even “.sarif-property” if “.sarif-externalized-property” is too long for your taste, but I personally favor consistency – in this case, consistency between the object name and the file extension – over brevity.)

 

Larry

 

From: Michael Fanning <Michael.Fanning@microsoft.com>
Sent: Saturday, October 20, 2018 4:54 PM
To: Larry Golding (Myriad Consulting Inc) <v-lgold@microsoft.com>; OASIS SARIF TC Discussion List <sarif@lists.oasis-open.org>
Subject: RE: external vs fragment redux

 

I’m not persuaded. Your argument appears to mostly hinge on the term ‘fragment’ causing confusion in the spec. I’m willing to yield that point but presumably, we should be tuning for how the file names read, not the spec. And I’m not convinced that file.sarif-external-file is sufficiently

 

Interestingly, I don’t share your sense of ‘fragment’ as irregular. By one standard definition of ‘fragment’, it is a clear use. 1. a small part broken or separated off something.

 

You can refer to these in the spec as ‘external fragments’ to create more consistency in your use of ‘externalizable.

 

I’d be glad to consider another term that is clearer than ‘external-files’ over ‘fragment’ if someone can suggest one. ‘Segment’, ‘section’ or ‘shard’ come closest to being appropriate, looking around on a synonym site.

 

Michael

 

 

From: sarif@lists.oasis-open.org <sarif@lists.oasis-open.org> On Behalf Of Larry Golding (Myriad Consulting Inc)
Sent: Thursday, October 18, 2018 10:42 AM
To: OASIS SARIF TC Discussion List <sarif@lists.oasis-open.org>
Subject: [sarif] external vs fragment redux

 

I don’t want to re-open the whole naming discussion but I want to talk more about the use of “fragment” to describe a run property stored in an external file. I was willing to yield this point because “.sarif-fragment” read nicely as a filename extension, but as I write the change draft, I see three problems:

 

1. The spec often talks about URI fragments. I’d like to avoid confusion about what “fragment” refers to, and I’d like not to have to qualify it everywhere (“URI fragment”, “SARIF fragment”). I know, I’ve often said that there are only a limited number of words in the language, but here we already have a distinct term (“external file”), and I’d like to avoid a change that introduces an ambiguity.
2. The spec uses words related to the term “external file”, for example “externalized” and “externalizable property”:

 

SARIF allows certain properties of a run object to be stored in separate files. We refer to these files as “external files”, and we refer to the file containing the run object itself as the “root file”. We refer to a property that can be stored in an external file as an “externalizable property.”

 

A SARIF consumer SHALL treat the contents of a property stored in an external file exactly as if they had appeared inline in the root file as the value of the corresponding property of the run object. In particular, this means that if the resources property (§3.11.16) is externalized, its contents take precedence over a resource file for the language specified by tool.language (§3.14.8) that might be located by the resource file lookup procedure (§3.9.6.3).

 

If an external file becomes a fragment, do we say that such a property is “fragmentable” or that it has been “fragmented” or “fragmentized”?

 

Mixing terminology isn’t great, either; you end up with this:

 

SARIF allows certain properties of a run object to be stored in separate files. We refer to these files as “fragment files”, and we refer to the file containing the run object itself as the “root file”. We refer to a property that can be stored in an external file as an “externalizable property.”

 

A SARIF consumer SHALL treat the contents of a property stored in an external file exactly as if they had appeared inline in the root file as the value of the corresponding property of the run object. In particular, this means that if the resources property (§3.11.16) is externalized, its contents take precedence over a resource file for the language specified by tool.language (§3.14.8) that might be located by the resource file lookup procedure (§3.9.6.3)

 

3. Aesthetics: I just don’t like the word “fragment” here. To my ear, it sounds like something “irregular”, something arbitrarily chopped out of the root file, something that you could incorporate back into the file with a #include-like mechanism.

 

Proposal: Keep the current terminology, and use the extension “.sarif-external-file” for external files.

 

Larry