Rename fileVersion to dottedQuadFileVersion and specify format constraint

[michaelcfanning]

See tool.fileVersion. Expressed on invocation.tool.fileVersion and conversion.tool.fileVersion

      "pattern": "[0-9]+(\\.[0-9]+){3}"

[ghost]

The schema says this, the spec doesn't have the words.

[ghost]

@michaelcfanning I think this issue is backwards. I don't think we should add words to the spec; I think we should remove the pattern from the schema.

The spec says:

If the operating system on which the tool runs provides a value for the file version of the tool's primary executable file, then the tool object MAY contain a property named fileVersion whose value is a string representation of that file version.

Sure, we know what Win32 and .NET represent the version with four dot-separated integers. But why should we require that? Maybe there's an OS that doesn't use that format. We talked about a representation that allowed any number of dot-separated numeric components, but why should we insist even on that? Just let it be a string, which is what the spec says today.

[michaelcfanning]

The operative qualifier in your comment is 'maybe'. This property today is precisely constructed (in the schema validation) to produce a file version that's completely compatible with the Windows platform. i.e., the value is guaranteed to be a valid Windows/.NET file version. That's nice. If we loosen requirements for a 'maybe' value, we've lost the guardrails for the driving scenario that led us to define this property.

My suggestion is to preserve the existing schema and make it clear this is for the Windows platform which implements file version metadata. we could name the property windowsFileVersion if that helps.

I found some information on VMS file versioning. VMS is a versioned file system, which means that files don't have a version, per se, the operating system retains a history of files. You can basically go request an historical revision of a file. Versions increment from 1 to an upper bound. But! there are also some special values. '*" for example, means all versions. A negative number can be used to specify 'give me the nth version of a file before the most recent version'. These special designations are not likely to be useful in a SARIF context, however, where a producer would want to explicitly identify a precise file revision (since a relative revision only makes sense at the point in time and could be hard or impossible to compute later).

https://winscp.net/forum/viewtopic.php?t=14962

[ghost]

I like your suggestion of renaming the property to windowsFileVersion -- it makes us completely transparent about the fact that we're adding something for the benefit of one particular OS.

Is there a trademark issue? (Like how you can't call your product "Windows File Munger", you have to call it "File Munger for Windows (TM)".)

[michaelcfanning]

This is a property name within a larger format, we're not actually branding anything ourselves, or referring to a specific product, If you looks at MS general feedback on trademarks, I think it's clear that we're not in this general domain.

However, just to be sure perhaps we name this thing 'windowsPlatformFileVersion' which makes it quite clear we are providing adjectival specifiers that qualify the kind of file version, rather than embedding a reference to a specific Microsoft product. Presumably, we have established a pattern for other version properties if they materialize, vmsPlatformFileVersion, etc.

https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general.aspx

[michaelcfanning]

I am fine with something like quadDottedFileVersion, as proposed in email.

[ghost]

Ok, I'll make that change and add the schema constraint.

[ghost]

This issue is labeled both bug, because it adds the missing syntactic constraint, and design-improvement, because of the (presumably) improved property name.

[michaelcfanning]

Presumed improved in the sense of allowing us to better conform to ISO standards around trademark use. :)

btw -based on the ISO standard, I suggest we go all in with their suggestion and update your text associated with EXAMPLE:

'On the Microsoft Windows (R) platform, this information is available in the FILEVERSION...'

Probably worth scrubbing for other 5 instances of 'Windows' use.

[ghost]

Done. I also confirmed that Linux ® and Unix ® are registered trademarks, so I scrubbed for that too. I applied all the fixes directly in the provisional draft.

I filed #290, "Add registered trademarks as appropriate" so I'd have an issue number to mention in the Editor's Report.