Request for comment: variables JSON schema

[voughtdq]

As has been discussed elsewhere, a data-oriented way to index variables would be helpful. Thoughts on a JSON schema like this? I was trying to think of a way that would add as few additional dependencies as possible while also providing a good experience for writing these files. While configuration languages like jsonnet are nice, it would require pulling in a golang dependency.

My idea is to write variables in a YAML file and then validate them with the JSON schema. I don't think the JSON schema works yet, but I was just looking for input on if I'm missing anything and whether this would be useful.

{
  "$id": "urn:freeswitch:variable",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "$defs": {
      "dataType": {
        "items": [
          "uuid",
          "dtmf_key",
          "boolean",
          "number",
          "positive_integer",
          "string",
          "tgml",
          "file_path",
          "execute_on",
          "regex"
        ],
        "type": "string"
      }
    },
    "dataTypes": {
      "description": "The type or types that can be assigned to this variable.",
      "items": {
        "$ref": "#/$defs/dataType"
      },
      "type": "array"
    },
    "deprecation": {
      "$comment": "Don't worry about digging to find this information now, it's just for new deprecations.",
      "description": "Provide upcoming deprecation information.",
      "properties": {
        "deprecated": {
          "default": false,
          "description": "Whether this variable has been deprecated.",
          "type": "boolean"
        },
        "deprecatedAsOfDate": {
          "$comment": "This can be autogenerated from the release date of the tag.",
          "description": "The date after which this variable is considered deprecated.",
          "type": "date"
        },
        "deprecatedAsOfVersion": {
          "$comment": "Use the git release tag.",
          "description": "The version tag that deprecates this variable.",
          "type": "version"
        }
      },
      "type": "object"
    },
    "description": {
      "description": "The description of this variable.",
      "type": "string"
    },
    "examples": {
      "description": "A list of examples for how this variable can be used.",
      "items": {
        "properties": {
          "description": {
            "type": "string"
          },
          "source_path": {
            "$comment": "Use this in lieu of a description string if you find that it's easier to reference a file for an example",
            "description": "The path to the example",
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "introduction": {
      "$comment": "Don't worry about about digging to find this information now, it's just for new variables.",
      "description": "When this variable was introduced.",
      "properties": {
        "introducedAsOfDate": {
          "$comment": "This can be autogenerated from the release date of the tag.",
          "description": "The date after which this variable was introduced.",
          "type": "date"
        },
        "introducedAsOfVersion": {
          "$comment": "Use the git release tag.",
          "description": "The version tag that introduced this variable.",
          "type": "version"
        }
      },
      "type": "object"
    },
    "isCoreVariable": {
      "$comment": "This can be autogenerated from the presence of at least one `src/*.c`, `src/*.cpp` or `src/include/*.h` in a file in the references key.",
      "description": "Whether this variable is referenced in the core.",
      "type": "boolean"
    },
    "name": {
      "description": "The name of the variable.",
      "type": "string"
    },
    "isReadOnly": {
      "$comment": "Set to null if it is dubious as to whether the variable is read only.",
      "default": false,
      "description": "Whether this variable can be assigned new values.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "references": {
      "description": "Where this variable gets defined in the code.",
      "items": {
        "$comment": "Links to the source can be autogenerated by combining the version tag with the path and line.",
        "properties": {
          "columnEnd": {
            "type": "integer"
          },
          "columnStart": {
            "type": "integer"
          },
          "line": {
            "type": "integer"
          },
          "path": {
            "$comment": "The path should look like: src/switch_channel.c",
            "description": "The path to the file in the repository",
            "type": "string"
          },
          "version": {
            "type": "version"
          }
        },
        "required": [
          "path",
          "line",
          "version"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "name"
  ],
  "title": "Variable",
  "type": "object"
}