[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: 'externalFiles' to 'externalFragments'?
If we did define a localized resource file format, Iâd want to change the current design that has it looking like a SARIF log file with some restrictions. Iâd just define a new top-level element sarifResources (see the pattern here? 😊) with properties
and leave it at that.
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: