Uh oh!
There was an error while loading. Please reload this page.
#521: Draft: JSON-based exchange format for OFT items and reports - #580
#521: Draft: JSON-based exchange format for OFT items and reports#580redcatbear wants to merge 9 commits into
Conversation
…ed-exchange-format' into documentation/521_draft-json-based-exchange-format
kaklakariada
left a comment
There was a problem hiding this comment.
General: looks very good!
Some more comments in the schema could help with understanding the proposal.
| "$schema": "https://json-schema.org/draft/2020-12/schema", | ||
| "$id": "https://github.com/itsallcode/openfasttrace/blob/main/doc/schemas/openfasttrace.schema.json", | ||
| "title": "OpenFastTrace JSON formats", | ||
| "description": "Schema for OpenFastTrace exchange (OFTX) and report (OFTR) documents. Properties whose value equals the declared default are omitted from serialized documents.", |
There was a problem hiding this comment.
Just an idea: this mixes exchange and reports. Would it be clearer to have separate schemas?
I guess it's less duplication to leave it like this.
There was a problem hiding this comment.
Yes, duplication avoidance is the main theme here. What ASPEC proved is that a machine-readable report is a list of items plus links plus verdict. That's a concept that I like and would like to keep.
| "reproducible": { | ||
| "type": "boolean", | ||
| "default": false, | ||
| "description": "Whether running OFT again with the recorded parameters can reproduce the document bit-identically." | ||
| }, |
There was a problem hiding this comment.
Do we need this? When is a report not reproducible? Only when the order in which files are read is different. But then OFT should sort the report reproducibly.
There was a problem hiding this comment.
Order, timestamps. Some people like to have timestamps in the reports as record. Good as historical document. Less so if you need it reproducible.
There was a problem hiding this comment.
I added the optional timestamp to the header. It can only be used when reproducible is set to false.
| "reference": { | ||
| "default": "relative", | ||
| "enum": [ | ||
| "absolute", | ||
| "relative" | ||
| ] |
There was a problem hiding this comment.
Does this mean that when the user specifies a relative path, the report contains only relative paths starting from that path, and when they specify an absolute path, all files under this path will be absolute in this report?
There was a problem hiding this comment.
Absolute paths seldom are useful in exchange. More so in a record (e.g., as proof of a tracing run). I understand "relative" as relative to the project root. Typically a repo checkout.
There was a problem hiding this comment.
Renamed to relativeToWorkingDirectory for better clarity.
| "oftx", | ||
| "oftr" |
There was a problem hiding this comment.
These constants are a bit cryptic. Could we write this out, e.g. "oft-exchange" or similar?
There was a problem hiding this comment.
Can do. I just thought we align that with the extension .oftx.json. But writing it out inside the document is OK.
There was a problem hiding this comment.
Changed to oftExchange and oftReport in alignement with the other enum values. Google JSON guide.
Uh oh!
There was an error while loading. Please reload this page.
| "locatedId": { | ||
| "type": "object", | ||
| "required": [ | ||
| "range" | ||
| ], | ||
| "properties": { | ||
| "range": { | ||
| "$ref": "#/$defs/range" | ||
| }, | ||
| "artifactType": { | ||
| "$ref": "#/$defs/range" | ||
| }, | ||
| "name": { | ||
| "$ref": "#/$defs/range" | ||
| }, | ||
| "revision": { | ||
| "$ref": "#/$defs/range" | ||
| } | ||
| }, | ||
| "additionalProperties": false | ||
| }, |
There was a problem hiding this comment.
Not sure if we need located IDs in the report. I would only add this if someone needs it.
There was a problem hiding this comment.
Think of it this way: a JSON based report fits nicely into a JavaScript report as Poldi did. Then you want location for jump URLs.
Co-authored-by: Christoph Pirkl <4711730+kaklakariada@users.noreply.github.com>
…ed-exchange-format' into documentation/521_draft-json-based-exchange-format
Discussion draft for the OFT's own native document interchange and report format.
Closes#521.