fileLocation uri property should be a URI reference

[lcartey]

The SARIF spec currently states:

A fileLocation object SHALL contain a property named uri whose value is a string containing a URI as described in [RFC3986].

However RFC 3986 states:

NOTE: Previous specifications used the terms "partial URI" and
"relative URI" to denote a relative reference to a URI. As some
readers misunderstood those terms to mean that relative URIs are a
subset of URIs rather than a method of referencing URIs, this
specification simply refers to them as relative references.

i.e. "relative URI"s are not themselves URIs. This is unfortunate, because it is common to store relative references in the fileLocation.uri property in conjunction with the uriBaseId property.

This confusion actually causes some issues for existing SARIF consumers. Currently, the SARIF schema specifies this:

        "uri": {
          "description": "A string containing a valid relative or absolute URI.",
          "type": "string",
          "format": "uri"
        },

However, "format": "uri" is a URI in the RFC 3986 sense, and does not permit scheme-less URIs such as relative references. This means a SARIF file with relative references in the URI will produce a warning when the file is validated strictly against the schema.

I noticed this because I tried loading one of our SARIF files in the Visual Studio Code SARIF extension, and it reported warnings on my relative references saying "String is not a URI: URI with a scheme is expected.". This is because VS Code correctly validates JSON files against their schemas (see here for where the VS Code JSON language service is processing the schema).

Concretely, I suggest we:

1. Modify the wording of the spec to say:

A fileLocation object SHALL contain a property named uri whose value is a string containing a URI reference as described in [RFC3986].

2. Replace uses of the term "relative URI" with "relative reference" or "relative URI reference".

3. Modify the schema to use uri-reference (see http://json-schema.org/latest/json-schema-validation.html#rfc.section.7.3.5) instead of uri for the fileLocation uri property, i.e.:

        "uri": {
          "description": "A string containing a valid relative or absolute URI.",
          "type": "string",
          "format": "uri-reference"
        },

[ghost]

@lukecartey @michaelcfanning Good catch! I labeled this issue as a bug, pulled it into CSD.1, and I'll have a change draft to review at TC #18 on 5/30.

[ghost]

... and your proposed changes look good.

[ghost]

@michaelcfanning After discussion on the DL, we agree that run.uriBaseIds can only contain non-deterministic URIs. The reason is that a post-processing tool that converts a SARIF file to deterministic form will omit run.uriBaseIds, and then (for example) I won’t be able find my work items any more.

So we agree that we use fileLocation only for non-deterministic URIs. So, as part of this issue, I now have to go through the spec and fix up the properties that incorrectly use fileLocation. I’ll have that change draft ready for TC #19.

[ghost]

The only existing properties whose value is an absolute-URI-valued string are:

• tool.downloadUri. This is correct.
• versionControlDetails.uri. This is correct.

The properties whose values are fileLocation objects are:

• result.workItemLocation is a deterministic fileLocation object. It needs to change to an absolute-URI-valued string.
• rule.helpLocation: This one is tricky. If the help files are on the machine, they're non-deterministic and we should use fileLocation. If they're on the web, they're deterministic and we should use an absolute-URI-valued string. Ideas?

All the other fileLocation-valued properties are non-deterministic, and so are using fileLocation appropriately.

[ghost]

Ignore the above two comments. I meant to add them to #175.