Skip to content

HDF Desc in SARIF FullDescription - #2634

Merged
Michael C. Fanning (michaelcfanning) merged 2 commits into
mainfrom
hdf-sarif-FullDescription
Mar 7, 2023
Merged

HDF Desc in SARIF FullDescription#2634
Michael C. Fanning (michaelcfanning) merged 2 commits into
mainfrom
hdf-sarif-FullDescription

Conversation

@candrews

Copy link
Copy Markdown
Collaborator

Store HDF Desc in SARIF FullDescription, not ShortDescription.

According to https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317845

A reportingDescriptor object MAY contain a property named shortDescription whose value is a localizable multiformatMessageString object (§3.12, §3.12.2) that provides a concise description of the reporting item. The shortDescription property SHOULD be a single sentence that is understandable when visible space is limited to a single line of text.

The HDF Desc tends to be a lot longer than a single sentence, oftentimes multiple sentences, sometimes multiple paragraphs. Therefore it is more appropriate for SARIF's FullDescription, according to https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317846

A reportingDescriptor object SHOULD contain a property named fullDescription whose value is a localizable multiformatMessageString object (§3.12, §3.12.2) that comprehensively describes the reporting item.

The fullDescription property SHOULD, as far as possible, provide details sufficient to enable resolution of any problem indicated by the reporting item.

The beginning of fullDescription (for example, its first sentence) SHOULD provide a concise description of the reporting item, suitable for display in cases where available space is limited. Tools that construct fullDescription in this way do not need to provide a value for shortDescription (§3.49.9). Tools that do not construct fullDescription in this way SHOULD provide a value for shortDescription.

Store HDF Desc in SARIF FullDescription, not ShortDescription.

According to https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317845
> A reportingDescriptor object MAY contain a property named shortDescription whose value is a localizable multiformatMessageString object (§3.12, §3.12.2) that provides a concise description of the reporting item. The shortDescription property SHOULD be a single sentence that is understandable when visible space is limited to a single line of text.

The HDF Desc tends to be a lot longer than a single sentence, oftentimes multiple sentences, sometimes multiple paragraphs. Therefore it is more appropriate for SARIF's FullDescription, according to https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317846
> A reportingDescriptor object SHOULD contain a property named fullDescription whose value is a localizable multiformatMessageString object (§3.12, §3.12.2) that comprehensively describes the reporting item.
>
> The fullDescription property SHOULD, as far as possible, provide details sufficient to enable resolution of any problem indicated by the reporting item.
>
> The beginning of fullDescription (for example, its first sentence) SHOULD provide a concise description of the reporting item, suitable for display in cases where available space is limited. Tools that construct fullDescription in this way do not need to provide a value for shortDescription (§3.49.9). Tools that do not construct fullDescription in this way SHOULD provide a value for shortDescription.
@candrews

Copy link
Copy Markdown
Collaborator Author

Michael C. Fanning (@michaelcfanning) how does this PR look?

I'm eager to get this merged and see the improvement in a release :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants