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:

 

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.

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)

 

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