Hi,

Thanks for all the discussion. Here's an updated spec with more detail
better descriptions and incorporating feedback.

I've made a JSON schema for the proposed format. Important notes:

  - Now supports holding information for multiple sources at once.
  - Logical provides has been folded down.
  - Property names can be bikeshedded. I've marked them all with a
    `bikeshed-` prefix.
  - Semantics of bits are described in `description` fields.
  - In `bikeshed-sources`, `bikeshed-input` values must be unique (I
    don't know how to indicate this in JSON Schema).
  - I don't know how to specify that unconstrained properties are not
    allowed and those starting with `_` are allowed. This apparently
    doesn't work:

    "patternProperties": {
      "^(_.*)$": {},
      "^(.*)$": /* ??? */
    }

    Suggestions welcome.

and relevant bits from the OP copied for convenience:

On Mon, Mar 04, 2019 at 17:57:53 -0500, Ben Boeckel wrote:
> - Relative paths are relative to the working directory of the
> compiler. Build tools may need to rewrite paths for the build tool
> to actually understand them.
> - `version` is bumped if there is any semantic data added (e.g., more
> information which is required to get a correct build), types change,
> etc.
> - `revision` is bumped if additionally helpful, but not semantically
> important, field is added to the format.

> Defined formats (I'm fine with bikeshedding these names once the overall
> format has been hammered out):
>
> - "raw8": interpret `data` as an array of uint8_t bytes to be passed
> to platform-specific filesystem APIs as an 8-bit encoding
> - "raw16": interpret `data` as an array of uint16_t bytes to be passed
> to platform-specific filesystem APIs as a 16-bit encoding
>
> This basically means "check if it is UTF-8, if it is, escape `\` and `"`
> and output that, otherwise indicate the byte size of the data and write
> it as an integer array".

==================== 8< ====================
{
  "$schema": "",
  "$id": "http://example.com/root.json",
  "type": "object",
  "title": "SG15 TR depformat",
  "definitions": {
    "filepath": {
      "$id": "#filepath",
      "type": [
        "object",
        "string"
      ],
      "description": "A filepath. Strings must be valid UTF-8. All other encodings should use raw data objects.",
      "minLength": 1,
      "required": [
        "bikeshed-format",
        "bikeshed-data"
      ],
      "properties": {
        "bikeshed-format": {
          "$id": "#format",
          "enum": ["bikeshed-raw8", "bikeshed-raw16"],
          "description": "Interpretation of the raw data bytes"
        },
        "bikeshed-data": {
          "$id": "#data",
          "type": "array",
          "description": "Raw filepath bytes",
          "minItems": 1,
          "items": {
            "type": "integer",
            "minimum": 1
          }
        }
      }
    },
    "depinfo": {
      "$id": "#depinfo",
      "type": "object",
      "description": "Dependency information for a source file",
      "required": [
        "bikeshed-input"
      ],
      "properties": {
        "bikeshed-input": {
          "$ref": "#/definitions/filepath"
        },
        "bikeshed-outputs": {
          "$id": "#outputs",
          "type": "array",
          "description": "Files output by this execution",
          "uniqueItems": true,
          "items": {
            "$ref": "#/definitions/filepath"
          }
        },
        "bikeshed-depends": {
          "$id": "#depends",
          "type": "array",
          "description": "Paths read during this execution",
          "uniqueItems": true,
          "items": {
            "$ref": "#/definitions/filepath"
          }
        },
        "bikeshed-future-compile": {
          "$ref": "#/definitions/future-depinfo"
        },
        "bikeshed-future-link": {
          "$ref": "#/definitions/future-depinfo"
        }
      }
    },
    "future-depinfo": {
      "$id": "#future-depinfo",
      "type": "object",
      "bikeshed-outputs": {
        "$id": "#outputs",
        "type": "array",
        "description": "Files output by a future rule for this source using the same flags",
        "uniqueItems": true,
        "items": {
          "$ref": "#/definitions/filepath"
        }
      },
      "bikeshed-provides": {
        "$id": "#provides",
        "type": "array",
        "description": "Modules provided by a future compile rule for this source using the same flags",
        "uniqueItems": true,
        "items": {
          "$ref": "#/definitions/module-desc"
        }
      },
      "bikeshed-requires": {
        "$id": "#requires",
        "type": "array",
        "description": "Modules required by a future compile rule for this source using the same flags",
        "uniqueItems": true,
        "items": {
          "$ref": "#/definitions/module-desc"
        }
      }
    },
    "module-desc": {
      "$id": "#module-desc",
      "type": "object",
      "required": [
        "bikeshed-logical"
      ],
      "properties": {
        "bikeshed-filepath": {
          "$ref": "#/definitions/filepath"
        },
        "bikeshed-logical": {
          "type": "string",
          "minLength": 1
        }
      }
    }
  },
  "required": [
    "version",
    "bikeshed-sources"
  ],
  "properties": {
    "version": {
      "$id": "#version",
      "type": "integer",
      "description": "The version of the output specification"
    },
    "revision": {
      "$id": "#revision",
      "type": "integer",
      "description": "The revision of the output specification",
      "default": 0
    },
    "bikeshed-sources": {
      "$id": "#sources",
      "type": "array",
      "title": "sources",
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/depinfo"
      }
    }
  }
}
==================== >8 ====================

You can play around online here with the JSON schema:

    https://www.jsonschemavalidator.net/

Thanks,

--Ben