DataSets Schema for Guest Access

This section shows JSON schema for the Datasets interfaces. For each DataSets command, input and output schema appear, followed by possible errors.

datasets-list – Return summary data about any DataSets, such as name and description.

no input schema

Output schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
          "description" : "A boolean specifying whether the RPC was successful."
    },
    "error-id": {
      "type": "string",
          "description": "If set, an error identifier for why the RPC failed."
    },
    "error-message": {
      "type": "string",
          "description": "If set, a usage message and error details for why the RPC failed."
    },
    "datasets": {
      "type": "array",
          "description": "The list of datasets and descriptions.",
          "examples": [
                    { "name": "dataset1", "description": "Description of dataset1" },
                    { "name": "dataset2", "description": "Description of dataset2" }
                  ],
       "items":
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "description"
          ]
        },
    }
  },
  "required": [
    "result",
    "datasets"
  ]
}

Possible error returned:

invalid-argument if there are any extraneous parameters.

datasets-query – Return a DataSet's attributes (description, usage, access).

Input schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "context": {
      "type": "string",
      "description": "The context value from a previous RPC with the same arguments to get the next page of output."
    },
   "dataset": {
      "type": "string",
      "description": "The name of the dataset from which to list the keys."
    }
  },
  "required": [
    "dataset"
  ]
}

Output schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
          "description" : "A boolean specifying whether the RPC was successful."
    },
    "error-id": {
      "type": "string",
          "description": "If set, an error identifier for why the RPC failed."
    },
    "error-message": {
      "type": "string",
          "description": "If set, a human-readable usage message and error details for why the RPC failed."
    },
    "info": {
      "type": "object",
      "description": "The attributes of the DataSet.",
      "examples": [
        { "name": "dsname1", "description" : "dsname1 description", "size": 12345, "used" : 2345, "hostAccess" : "READ_WRITE", "guestAccess" : "READ_ONLY", "omitFromSnapshotAndClone" : false }
         ],
 
     "items":   [
       {
       "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the DataSet."
            },
            "description": {
              "type": "string",
              "description" : "The description of the DataSet."
            },
            "used": {
              "type": "number",
              "description": "The number of bytes in use by the DataSet."
            },
            "hostAccess" : {
               "type": "string",
               "description" : "The access from the host."
            },
            "guestAccess" : {
               "type": "string",
                "description" : "The access from the guest."
            }
            "omitFromSnapshotAndClone": {
                "type": "boolean",
                "description": "If true, the data set is considered a property of the virtual machine, and is not included in a snapshot operation or when the virtual machine is cloned."
            }
          },
          "required": [
            "name",
            "description",
            "used",
            "hostAccess",
            "guestAccess",
            "omitFromSnapshotAndClone"
          ]
        },
      ],
    },
  },
  "required": [
    "result",
    "info"
  ]
}

Possible errors returned:

invalid-argument if the specified JSON is invalid or arguments are missing or malformed.
dataset-not-found if the supplied dataset does not exist.

datasets-get-entry – Get the value of one or more keys in a DataSet.

Input schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "description": "DataSet from which to get entries."
    },
    "context": {
       "type": "string",
       "description": "The context value from a previous RPC with the same arguments to get the next page of output."
    },
    "keys": {
      "type": "array",
      "description": "Entries to get.",
      "items": [
        {
          "type": "string"
          "description": "The key being requested."
        },
      ]
    }
  },
  "required": [
    "dataset",
    "keys"
  ]
}

Output schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "string"
    },
    "error-id": {
      "type": "string",
          "description": "If set, an error identifier for why the RPC failed."
    },
    "error-message": {
      "type": "string",
      "description": "If set, a human-readable usage message and error details for why the RPC failed."
    },
    "context": {
      "type": "string",
      "description": "If set, a value that can be passed in to the RPC with the same arguments to get the next page of output."
    },
    "entries": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "key": {
              "type": "string",
              "description": "The queried key and value."
            },
          },
          "required": [
            "key"
          ]
        },
      ]
    }
  },
  "required": [
    "result",
    "entries"
  ]
}

Possible errors returned:

invalid-argument if the specified JSON is invalid or arguments are missing or malformed.
dataset-not-found if the specified dataset does not exist.
invalid-context if the specified context is invalid.

datasets-set-entry – Set the value of one or more keys in a DataSet.

Input schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "description": "DataSet in which to set the entries."
    },
    "entries": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "key": {
              "type": "string",
              "description": "The key being set."
            },
            "value": {
              "type": "string",
              "description": "The new value for the key."
            },
            "append": {
              "type": "boolean",
              "description": "If set, the value is appended to any current value, or set if this is a new key."
            },
          },
          "required": [
              "key",
              "value",
          ]
        },
      ],
    },
  },
  "required": [
      "dataset",
      "entries"
   ]
}

Output schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description" : "A boolean specifying whether the RPC was successful."
    },
    "error-id": {
      "type": "string",
          "description": "If set, an error identifier for why the RPC failed."
    },
    "error-message": {
      "type": "string",
      "description": "If set, a human-readable usage message and error details for why the RPC failed."
    },
  },
  "required": [
    "result"
  ]
}

Possible errors returned:

invalid-argument if the specified JSON is invalid or arguments are missing or malformed.
dataset-not-found if the specified dataset does not exist.
out-of-space if the total data exceeds the maximum allowed.

datasets-list-keys – Enumerate the keys in a DataSet.

Input schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "context": {
      "type": "string",
      "description": "The context value from a previous RPC with the same arguments to get the next page of output."
    },
   "dataset": {
      "type": "string",
      "description": "The name of the dataset from which to list the keys."
    }
  },
  "required": [
    "dataset"
  ]
}

Output schema.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description" : "A boolean specifying whether the RPC was successful."
    },
    "error-id": {
      "type": "string",
          "description": "If set, an error identifier for why the RPC failed."
    },
    "error-message": {
      "type": "string",
      "description": "If set, a human-readable usage message and error details for why the RPC failed."
    },
    "context": {
      "type": "string",
      "description": "If set, a value that can be passed in to the RPC with the same arguments to get the next page of output."
    },
    "keys": {
      "type": "array",
      "description": "The list of keys in the dataset.",
      "examples": [ "key1", "key2", "key3" ]
    }
  },
  "required": [
    "result",
    "keys"
  ]
}

Possible errors returned:

invalid-argument if the specified JSON is invalid or arguments are missing or malformed.
dataset-not-found if the specified dataset does not exist.
invalid-context if the specified context is invalid.

datasets-delete-entry – deletes one or more entries in a DataSet.

Input schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "description": "DataSet from which to delete entries."
    },
    "keys": {
      "type": "array",
      "description": "Entries to delete.",
      "items": [
        {
          "type": "string"
        },
      ]
    }
  },
  "required": [
    "dataset",
    "keys"
  ]
}

Output schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description" : "A boolean specifying whether the RPC was successful."
    },
    "error-id": {
      "type": "string",
          "description": "If set, an error identifier for why the RPC failed."
    },
    "error-message": {
      "type": "string",
      "description": "If set, a human-readable usage message and error details for why the RPC failed."
    },
  },
  "required": [
    "result"
  ]
}

Possible errors returned:

invalid-argument if the specified JSON is invalid or arguments are missing or malformed.
dataset-not-found if the specified dataset does not exist.
key-not-found if the specified key does not exist.

Table of Error Codes

Typedef enumeration	Generic error message	Description
`ERROR_SUCCESS`	JSON response returned.	Not an error.
`ERROR_DATASET_NOT_FOUND`	DataSet `ds-name` not found.	DataSet not yet created.
`ERROR_KEY_NOT_FOUND`	Key `k-name` not found.	Attribute key not yet created.
`ERROR_INVALID_ARGUMENT`	Invalid argument: `arg`.	Malformed JSON or arguments.
`ERROR_INVALID_CONTEXT`	Invalid context: `context`.	Probably key does not exist in DataSet.
`ERROR_ACCESS_DENIED`	Access denied to DataSet `ds-name`.	Not authorized for this operation.
`ERROR_OUT_OF_SPACE`	Insufficient resources: `datum`.	Message passed was too large.
`ERROR_GENERIC`	Error: `error-message`.	Some other error.