OFT's native specification item file format

[redcatbear]

Situation

For data exchange we currently support the machine readable "SpecObject" and "ASPEC" formats. While these are technically sufficient, they show their heritage over three predecessor tools (TReqs, ReqM2 and Allosaurus). They could be a lot more streamlined and user-friendly.

Implementation Idea

We should add a machine-readable exchange format with JSON, that is closer to who OFT sees the data, more compact and less convoluted than OSPEC and ASPEC.

Sample File

{
  "$schema": "http://schemas.itsallcode.org/oft/oft_specitem_1.0.json",
  "creationDate": "<ISO creation date>",
  "oftVersionUsed": "<version of OFT that was used to create the file>",
  "formatVersion": "1.0",
  "specificationItems": [
    {
      "id": "...",
      "title": "...",
      "description": "...",
      "rationale": "...",
      "comment": "...",
      "status": "..."
      "covers": ["cover_id_1", "cover_id_2"],
      "depends": ["dep_id_1", "dep_id_2"],
      "tags": ["tag_1", "tag_2"],
      "source": {
        "file": "<path to source file>",
        "line": <line in source file>
      },
    },
    ...
  ]
}

Potential Libraries

Name	License	Project Home Page Link	Single Library	Estimated JAR Size	Last Release Date
Gson	Apache 2.0 License	Gson on GitHub	Yes	~230 KB
Jackson	Apache 2.0 License	Jackson on GitHub	Yes	~1.4 MB
Json-simple	Apache 2.0 License	Json-simple on GitHub	Yes	~25 KB
org.json	JSON License	Org.JSON in Maven Repository	Yes	~66 KB
JSON-java	BSD 3-Clause License	JSON-java on GitHub	Yes	~63 KB

[redcatbear]

Here's a first draft of the JSON schema:

{
  "$id": "ttp://schemas.itsallcode.org/oft/oft_specitem_1.0.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "creationDate": {
      "type": "string",
      "format": "date-time"
    },
    "oftVersionUsed": {
      "type": "string"
    },
    "formatVersion": {
      "type": "string"
    },
    "specificationItems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "rationale": {
            "type": "string"
          },
          "covers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "depends": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "object",
            "properties": {
              "file": {
                "type": "string"
              },
              "line": {
                "type": "string"
              }
            },
            "required": ["file", "line"]
          },
          "comment": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": ["id", "title", "description", "rationale", "covers", "depends", "tags", "source", "comment", "status"]
      }
    }
  },
  "required": ["creationDate", "oftVersionUsed", "formatVersion", "specificationItems"]
}