Ok. We have a remaining open issue in this area. In the last TC, we discussed how the resources files fit into this general schema of things. We should think about this a bit more. I reviewed the spec information. First, it appears that
we do define a specific format for the resources object. But we’ve never created or published a schema for it. We also don’t have a proof point for utilizing it.
In the TC, we wondered: should we forbid resources as fragments because we have the alternate resource file?
I argued that for consistency, we should permit resources as fragments: it keeps the design consistent in all cases, even when localization is nowhere in sight as a topic. We did not thoroughly discuss a different approach: can we dispense
with the ‘resources’ file definition by replacing it with a fragment?
On surface, this looks attractive: we eliminate a schema/file format and we could eliminate a dedicated file extension for *.sarif-resources as well. There is at least one problem with doing so: we have an optional tight coupling of a fragment
with a root SARIF file. For resources, the coupling is with a specific version of a tool, not a specific log file. i.e., a resources file would comprise, e.g., all EN strings for blah tool, v1.1.2. The custom resources format accounts for this, a fragment
currently cannot.
Michael
From: Larry Golding (Myriad Consulting Inc) <>
Sent: Wednesday, October 17, 2018 12:07 PM
To: Larry Golding (Myriad Consulting Inc) <>; Michael Fanning <>; 'OASIS SARIF TC Discussion List' <>
Subject: RE: 'externalFiles' to 'externalFragments'?
Ok according to
https://tools.ietf.org/html/rfc2045.
From: <>
On Behalf Of Larry Golding (Myriad Consulting Inc)
Sent: Wednesday, October 17, 2018 12:02 PM
To: Michael Fanning <>; 'OASIS SARIF TC Discussion List' <>
Subject: [sarif] RE: 'externalFiles' to 'externalFragments'?
Thanks. I updated #182 to propose
application/sarif-fragment+json. I’ll check the MIME type RFC to make sure “hyphen” is ok.
From: Michael Fanning <>
Sent: Wednesday, October 17, 2018 12:00 PM
To: Larry Golding (Myriad Consulting Inc) <>; 'OASIS SARIF TC Discussion List' <>
Subject: RE: 'externalFiles' to 'externalFragments'?
I like your proposal! We need to make sure we request all relevant MIME types as well, I think we require one additional one minimally for SARIF fragments.
From: Larry Golding (Myriad Consulting Inc) <>
Sent: Wednesday, October 17, 2018 11:54 AM
To: Michael Fanning <>; 'OASIS SARIF TC Discussion List' <>
Subject: RE: 'externalFiles' to 'externalFragments'?
Importance: High
I
I captured a proposal based on this discussion in an
issue comment; please review – thanks!
From: Larry Golding (Myriad Consulting Inc) <>
Sent: Wednesday, October 17, 2018 10:06 AM
To: Larry Golding (Myriad Consulting Inc) <>; Michael Fanning <>; 'OASIS SARIF TC Discussion List' <>
Subject: RE: 'externalFiles' to 'externalFragments'?
By the way, Michael and I were having this discussion in the context of working to close the existing Issue #118, “SARIF file naming convention”. We are not proposing to open a new issue. It we did decide (for example) to rename externalFiles
to externalFragments, we would do it in the context of #118.
Hey! Why not name it (“it” being the thing we today call a “externalFile”)
sarifFragment rather than externalFragment? That is parallel to the existing
sarifLog type! And it would then map most naturally to the filename extension “sarif-fragment”.
Larry
From: <>
On Behalf Of Larry Golding (Myriad Consulting Inc)
Sent: Wednesday, October 17, 2018 10:02 AM
To: Michael Fanning <>; 'OASIS SARIF TC Discussion List' <>
Subject: [sarif] RE: 'externalFiles' to 'externalFragments'?
“sarif-fragment” is nice because it suggests “sarif-resources” as the extension for the language-specific resource files defined elsewhere in the spec. If “-sarif” is at the end of the extension, you end up with “resources-sarif” which
doesn’t read as well.
From: <>
On Behalf Of Michael Fanning
Sent: Wednesday, October 17, 2018 7:31 AM
To: 'OASIS SARIF TC Discussion List' <>
Subject: [sarif] 'externalFiles' to 'externalFragments'?
Larry and I were discussing a possible rename yesterday, just sanity checking this with the group. We were specifically noting that we require a naming convention to help distinguish ‘external’ files. The reason is that their only distinguishing
characteristic within the file is the $scheme property, which is optional (the version property matches a root/parent SARIF file).
And so a convention to name these files something like *.external.sarif would be useful. Alternately, of course, we could consider defining an entirely new extension, e.g., external-sarif.
When considering either a new extension or a file naming convention, it occurred to me that the use of the term ‘fragment’ would be clearer. And so I have two questions:
What would people think about using ‘externalFragments’ as a name rather than ‘externalFiles’? This would be minimally intrusive in the spec and lead to file names such as ‘example.fragment.sarif’,
which is clearer than ‘example.external.sarif’.
What mechanism should we prefer, a naming convention or a new extension? I,.e., ‘example.fragment.sarif’ or ‘example.fragment-sarif’? or even ‘example.sarif-fragment’ (which is entirely
readable)
Michael
