#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 4 commits into
Conversation
…ed-exchange-format' into documentation/521_draft-json-based-exchange-format
kaklakariada
left a comment
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.
| "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.
| "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.
| "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.
| "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.
github-project-automation
Bot
moved this from 📫 Backlog
to 🔨 In Progress
in OpenFastTrace
Co-authored-by: Christoph Pirkl <4711730+kaklakariada@users.noreply.github.com>
|
2 participants
Discussion draft for the OFT's own native document interchange and report format.
Closes #521.