[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Editorial: Issue #213: Avoid JSON terminology
I don’t usually notify you of editorial changes, but this one might be of some interest: Issue #213: “Avoid JSON terminology where possible.” I made the changes directly in the provisional draft, but I also provided a change draft so you can see these changes in isolation.
The most interesting change is in Section 3.1 (File format: General), where I take care to distinguish the object model from the serialization:
SARIF defines an object model, the top level of which is the sarifLog object (§3.10), which contains the results of a one or more analysis runs. The runs do not need to be produced by the same analysis tool.
A SARIF log file SHALL contain a serialization of the SARIF object model into the JSON format.
NOTE 1: In the future, other serializations might be defined.
The top-level value in the log file, representing the sarifLog object, SHALL conform to the JSON object grammar; that is, it SHALL consist of a comma-separated sequence of name/value pairs, enclosed in curly brackets, as described in [ ].
A SARIF log file SHALL be encoded in UTF-8 .
NOTE 2:  requires this encoding for any JSON text “exchanged between systems that are not part of a closed ecosystem.”
The rest of the changes are mechanical, mostly replacing “JSON object” with “object” in the dozen or so places it occurs.
I have not completely disentangled the definition of the object model from its serialization. For example, there are places where I say that a property can have “any JSON value”, or where I specify the string value of a property to use JSON escaping. But IMO this is certainly good enough for CSD.2, and probably good enough for the final release. The day we define another serialization will be soon enough to do the rest of the refactoring. For now, the fact that we clarify up front the distinction between object model and serialization is IMO good enough.