Subject: RE: 'externalFiles' to 'externalFragments'?
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.
That is correct. At the time I argued in favor of a separate schema for localized resource files, precisely to allow me to write spec text that restricted the properties that could appear in a resource file. You didn’t want to do that (I don’t remember why). We did not carry that discussion to a conclusion. As a result, the spec is in this inconsistent state where it places verbal restrictions on SARIF files used to hold localized resources. In some cases these restrictions are inconsistent with the SARIF root file schema (for example, run.resources must be present in a resource file, but it’s optional in a SARIF root file), and in other cases they cannot be enforced by the SARIF root file schema (for example, a localized resource file must not contain run.results, but run.results is optional in a SARIF root file).
I still think we should define a localized resource file schema.
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.
I agree with that, and there is spec text that explains how the two mechanisms interact.
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.
… and exactly.
Ok according to https://tools.ietf.org/html/rfc2045.
Thanks. I updated #182 to propose application/sarif-fragment+json. I’ll check the MIME type RFC to make sure “hyphen” is ok.
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.
I captured a proposal based on this discussion in an issue comment; please review – thanks!
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”.
“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.
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: