schemas/macro_service.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "$ref": "#/$defs/HostRequest"
    },
    {
      "$ref": "#/$defs/MacroRequest"
    },
    {
      "$ref": "#/$defs/Response"
    }
  ],
  "$defs": {
    "AugmentRequest": {
      "type": "object",
      "description": "A request to a macro to augment some code.",
      "properties": {
        "phase": {
          "description": "Which phase to run: 1, 2 or 3.",
          "type": "integer"
        },
        "target": {
          "$comment": "The class to augment. TODO(davidmorgan): expand to more types of target",
          "$ref": "file:dart_model.schema.json#/$defs/QualifiedName"
        }
      }
    },
    "AugmentResponse": {
      "type": "object",
      "description": "Macro's response to an [AugmentRequest]: the resulting augmentations.",
      "properties": {
        "augmentations": {
          "description": "The augmentations.",
          "type": "array",
          "items": {
            "$ref": "file:dart_model.schema.json#/$defs/Augmentation"
          }
        }
      }
    },
    "ErrorResponse": {
      "type": "object",
      "description": "Request could not be handled.",
      "properties": {
        "error": {
          "description": "The error.",
          "type": "string"
        }
      }
    },
    "HostEndpoint": {
      "type": "object",
      "description": "A macro host server endpoint. TODO(davidmorgan): this should be a oneOf supporting different types of connection. TODO(davidmorgan): it's not clear if this belongs in this package! But, where else?",
      "properties": {
        "port": {
          "description": "TCP port to connect to.",
          "type": "integer"
        }
      }
    },
    "HostRequest": {
      "$description": "A request sent from host to macro.",
      "properties": {
        "id": {
          "description": "The id of this request, must be returned in responses.",
          "type": "integer"
        },
        "type": {
          "type": "string"
        },
        "value": {
          "oneOf": [
            {
              "$ref": "#/$defs/AugmentRequest"
            }
          ]
        }
      },
      "required": [
        "id",
        "type",
        "value"
      ]
    },
    "MacroDescription": {
      "type": "object",
      "description": "Information about a macro that the macro provides to the host.",
      "properties": {
        "runsInPhases": {
          "description": "Phases that the macro runs in: 1, 2 and/or 3.",
          "type": "array",
          "items": {
            "type": "integer"
          }
        }
      }
    },
    "MacroStartedRequest": {
      "type": "object",
      "description": "Informs the host that a macro has started.",
      "properties": {
        "macroDescription": {
          "$ref": "#/$defs/MacroDescription"
        }
      }
    },
    "MacroStartedResponse": {
      "type": "object",
      "description": "Host's response to a [MacroStartedRequest]."
    },
    "MacroRequest": {
      "$description": "A request sent from macro to host.",
      "properties": {
        "id": {
          "description": "The id of this request, must be returned in responses.",
          "type": "integer"
        },
        "type": {
          "type": "string"
        },
        "value": {
          "oneOf": [
            {
              "$ref": "#/$defs/MacroStartedRequest"
            },
            {
              "$ref": "#/$defs/QueryRequest"
            }
          ]
        }
      },
      "required": [
        "id",
        "type",
        "value"
      ]
    },
    "Protocol": {
      "type": "object",
      "description": "The macro to host protocol version and encoding. TODO(davidmorgan): add the version.",
      "properties": {
        "encoding": {
          "type": "string",
          "description": "The wire format: json or binary. TODO(davidmorgan): use an enum?"
        }
      }
    },
    "QueryRequest": {
      "type": "object",
      "description": "Macro's query about the code it should augment.",
      "properties": {
        "query": {
          "$ref": "file:dart_model.schema.json#/$defs/Query"
        }
      }
    },
    "QueryResponse": {
      "type": "object",
      "description": "Host's response to a [QueryRequest].",
      "properties": {
        "model": {
          "$ref": "file:dart_model.schema.json#/$defs/Model"
        }
      }
    },
    "Response": {
      "$description": "A response to a request.",
      "properties": {
        "requestId": {
          "description": "The id of the request this is responding to.",
          "type": "integer"
        },
        "type": {
          "type": "string"
        },
        "value": {
          "oneOf": [
            {
              "$ref": "#/$defs/AugmentResponse"
            },
            {
              "$ref": "#/$defs/ErrorResponse"
            },
            {
              "$ref": "#/$defs/MacroStartedResponse"
            },
            {
              "$ref": "#/$defs/QueryResponse"
            }
          ]
        }
      },
      "required": [
        "requestId",
        "type",
        "value"
      ]
    }
  }
}