HAPI-data-access-schema-3.1.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "HAPI": {
    "id": "/HAPI",
    "description": "HAPI Version",
    "type": "string",
    "pattern": "^3\\.1$"
  },
  "HAPIDateTime": {
    "id": "/HAPIDateTime",
    "description": "Regular expressions to handle some basic allowed HAPI date/time formats (a subset of ISO 8601). All times should pass this basic test. Additional tests for valid DOY and DOM are done in code.",
    "anyOf": [
      {
        "$ref": "/RefOrString"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-([0-2][0-9][0-9]|3[0-5][0-9]|36[0-6])Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-([0-2][0-9][0-9]|3[0-5][0-9]|36[0-6])T([0-1][0-9]|2[0-4])Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-([0-2][0-9][0-9]|3[0-5][0-9]|36[0-6])T(([0-1][0-9]|2[0-3]):([0-5][0-9])|24:00)Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-([0-2][0-9][0-9]|3[0-5][0-9]|36[0-6])T(([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(\\.([0-9]{0,9}))?|24:00:00(\\.(0{0,9}))?)Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([0-1][0-9]|2[0-4])Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T(([0-1][0-9]|2[0-3]):([0-5][0-9])|24:00)Z$"
      },
      {
        "type": "string",
        "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T(([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(\\.([0-9]{0,9}))?|24:00:00(\\.(0{0,9}))?)Z$"
      },
      {
        "type": "string",
        "pattern": "^(1972|1981|1982|1983|1985|1992|1993|1994|1997|2012|2015)-06-30T23:59:60(\\.[0-9]{0,9})?Z"
      },
      {
        "type": "string",
        "pattern": "^(197[1-9]|1987|1989|1990|1995|1998|2005|2008|2016)-12-31T23:59:60(\\.[0-9]{0,9})?Z"
      },
      {
        "type": "string",
        "pattern": "^(1972|1992|2012)-182T23:59:60(\\.[0-9]{0,9})?Z"
      },
      {
        "type": "string",
        "pattern": "^(1981|1982|1983|1985|1993|1994|1997|2015)-181T23:59:60(\\.[0-9]{0,9})?Z"
      },
      {
        "type": "string",
        "pattern": "^(1972|2008|2016)-366T23:59:60(\\.[0-9]{0,9})?Z"
      },
      {
        "type": "string",
        "pattern": "^(1971|197[3-9]|1987|1989|1990|1995|1998|2005)-365T23:59:60(\\.[0-9]{0,9})?Z"
      }
    ]
  },
  "HAPIStatus": {
    "id": "/HAPIStatus",
    "description": "Request status",
    "oneOf": [
      {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "patternProperties": {
          "x_.*": {}
        },
        "additionalProperties": false,
        "properties": {
          "code": {
            "description": "HAPI request status code",
            "type": "integer",
            "enum": [
              1200,
              1201,
              1400,
              1401,
              1402,
              1403,
              1404,
              1405,
              1406,
              1407,
              1408,
              1409,
              1410,
              1411,
              1412,
              1500,
              1501
            ]
          },
          "message": {
            "description": "HAPI request status message",
            "type": "string"
          }
        }
      },
      {
        "$ref": "/Ref"
      }
    ]
  },
  "UnitsAndLabelCommon": {
    "id": "/UnitsAndLabelCommon",
    "description": "Common parts of units and label schema",
    "oneOf": [
      {
        "type": "string",
        "minLength": 1,
        "pattern": "\\S"
      },
      {
        "type": [
          "array"
        ],
        "items": [
          {
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          }
        ],
        "minItems": 1
      },
      {
        "type": [
          "array"
        ],
        "items": [
          {
            "type": "array"
          }
        ],
        "minItems": 1
      },
      {
        "$ref": "/Ref"
      }
    ]
  },
  "RefOrString": {
    "id": "/RefOrString",
    "description": "JSON reference",
    "oneOf": [
      {
        "type": "string"
      },
      {
        "$ref": "/Ref"
      }
    ]
  },
  "Ref": {
    "id": "/Ref",
    "description": "JSON reference",
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "$ref": {
        "type": "string",
        "pattern": "\\#\\/definitions\\/.*"
      }
    }
  },
  "about": {
    "title": "about",
    "description": "Server /about response",
    "type": "object",
    "required": [
      "HAPI",
      "status",
      "id",
      "title",
      "contact"
    ],
    "patternProperties": {
      "x_.*": {}
    },
    "additionalProperties": false,
    "properties": {
      "HAPI": {
        "$ref": "/HAPI"
      },
      "status": {
        "$ref": "/HAPIStatus"
      },
      "id": {
        "description": "A unique ID for the server. Ideally, this ID has the organization name in it, e.g., NASA/SPDF/SSCWeb, NASA/SPDF/CDAWeb, INTERMAGNET, UniversityIowa/VanAllen, LASP/TSI, etc.",
        "type": "string"
      },
      "title": {
        "description": "A short human-readable name for the server. The suggested maximum length is 40 characters.",
        "type": "string"
      },
      "contact": {
        "description": "Contact information or email address for server issues. HAPI clients should show this contact information when it is certain that an error is due to a problem with the server (as opposed to the client).",
        "type": "string"
      },
      "contactID": {
        "description": "The identifier in the discovery system for information about the contact. For example, a SPASE ID of a person identified in the contact string.",
        "type": "string"
      },
      "description": {
        "description": "A brief description of the type of data the server provides.",
        "type": "string"
      },
      "citation": {
        "description": "How to cite the server. An actionable DOI is preferred (e.g., https://doi.org/...). This citation differs from the citation in an /info response. Here the citation is for the entity that maintains the data server.",
        "type": "string"
      }
    }
  },
  "capabilities": {
    "title": "capabilities",
    "description": "Server /capabilities response",
    "type": "object",
    "required": [
      "HAPI",
      "status",
      "outputFormats"
    ],
    "patternProperties": {
      "x_.*": {}
    },
    "additionalProperties": false,
    "properties": {
      "HAPI": {
        "$ref": "/HAPI"
      },
      "status": {
        "$ref": "/HAPIStatus"
      },
      "outputFormats": {
        "description": "Output formats",
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "csv",
            "binary",
            "json"
          ]
        },
        "minItems": 1,
        "additionalItems": true,
        "uniqueItems": true
      }
    }
  },
  "catalog": {
    "title": "catalog",
    "description": "Server /catalog response",
    "type": "object",
    "required": [
      "HAPI",
      "status",
      "catalog"
    ],
    "patternProperties": {
      "x_.*": {}
    },
    "additionalProperties": false,
    "properties": {
      "HAPI": {
        "$ref": "/HAPI"
      },
      "status": {
        "$ref": "/HAPIStatus"
      },
      "catalog": {
        "description": "Catalog of datasets",
        "type": "array",
        "minItems": 1,
        "additionalItems": true,
        "uniqueItems": true,
        "items": {
          "type": "object",
          "required": [
            "id"
          ],
          "patternProperties": {
            "x_.*": {}
          },
          "additionalProperties": false,
          "properties": {
            "id": {
              "description": "Dataset ID",
              "type": "string",
              "uniqueItems": true
            },
            "title": {
              "description": "Optional dataset title",
              "type": "string",
              "uniqueItems": true
            }
          }
        }
      }
    }
  },
  "info": {
    "title": "info",
    "description": "Server /info response",
    "type": "object",
    "required": [
      "HAPI",
      "status",
      "startDate",
      "stopDate",
      "parameters"
    ],
    "patternProperties": {
      "x_.*": {}
    },
    "additionalProperties": false,
    "dependencies": {
      "sampleStartDate": [
        "sampleStopDate"
      ],
      "sampleStopDate": [
        "sampleStartDate"
      ]
    },
    "properties": {
      "HAPI": {
        "$ref": "/HAPI"
      },
      "status": {
        "$ref": "/HAPIStatus"
      },
      "format": {
        "description": "Output format",
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "csv",
              "binary",
              "json"
            ]
          },
          {
            "$ref": "/Ref"
          }
        ]
      },
      "startDate": {
        "description": "start date/time of parameter data (inclusive)",
        "$ref": "/HAPIDateTime"
      },
      "stopDate": {
        "description": "stop date/time of parameter data (exclusive)",
        "$ref": "/HAPIDateTime"
      },
      "timeStampLocation": {
        "description": "Indicates the positioning of the time stamp within the measurement window.",
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "begin",
              "center",
              "end",
              "other"
            ]
          },
          {
            "$ref": "/Ref"
          }
        ]
      },
      "sampleStartDate": {
        "description": "start of a sample time period for a dataset (inclusive), where the time period should contain a manageable, representative example of valid, non-fill data",
        "$ref": "/HAPIDateTime"
      },
      "sampleStopDate": {
        "description": "stop date/time associated with sampleStartDate (exclusive)",
        "$ref": "/HAPIDateTime"
      },
      "cadence": {
        "description": "Time difference between records as an ISO 8601 duration. This is meant as a guide to the nominal cadence of the data and not necessarily a precise statement about the time between measurements.",
        "$ref": "/RefOrString"
      },
      "maxRequestDuration": {
        "description": "An ISO 8601 duration indicating the maximum duration for a request. This duration should be interpreted by clients as a limit above which a request for all parameters will very likely be rejected with a HAPI 1408 error; requests for fewer parameters and a longer duration may or may not be rejected.",
        "$ref": "/RefOrString"
      },
      "description": {
        "description": "A brief description of the dataset",
        "$ref": "/RefOrString"
      },
      "resourceURL": {
        "description": "a link to more information about the dataset",
        "$ref": "/RefOrString"
      },
      "resourceID": {
        "description": "an external identifier by which other datasets might know this dataset, such as a DOI or SPASE ID",
        "$ref": "/RefOrString"
      },
      "creationDate": {
        "description": "the date and time when this dataset was created",
        "$ref": "/HAPIDateTime"
      },
      "modificationDate": {
        "description": "the date and time when this dataset was last modified",
        "$ref": "/HAPIDateTime"
      },
      "contact": {
        "description": "the name of a person to contact for more information about the dataset",
        "$ref": "/RefOrString"
      },
      "contactID": {
        "description": "the identifier for the contact person in an external data system",
        "$ref": "/RefOrString"
      },
      "unitsSchema": {
        "description": "a string identifying the units convention",
        "oneOf": [
          {
            "$ref": "/Ref"
          },
          {
            "type": "string",
            "enum": [
              "udunits2",
              "astropy3",
              "cdf-cluster"
            ]
          }
        ]
      },
      "coordinateSystemSchema": {
        "description": "The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any coordinateSystemName keyword given in a parameter definition should follow this schema.",
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "spase2.4.1"
            ]
          },
          {
            "$ref": "/Ref"
          }
        ]
      },
      "citation": {
        "description": "How to cite the data set. An actionable DOI is preferred (e.g., https://doi.org/...). This citation differs from the citation in an /info response. Here the citation is for the entity that maintains the data server.",
        "$ref": "/RefOrString"
      },
      "additionalMetadata": {
        "description": "A way to include a block of other (non-HAPI) metadata. See below for a description of the object, which can directly contain the metadata or point to it via a URL.",
        "type": "object",
        "oneOf": [
          {
            "$ref": "/Ref"
          },
          {
            "required": [
              "content"
            ],
            "additionalProperties": false,
            "properties": {
              "name": {
                "description": "the name of the additional metadata",
                "type": "string"
              },
              "content": {
                "description": "Either a string with the metadata content (for XML), or a JSON object representing the object tree for the additional metadata",
                "type": [
                  "object",
                  "string"
                ]
              },
              "schemaURL": {
                "description": "A computer-readable schema for the additional metadata",
                "type": "string"
              },
              "aboutURL": {
                "description": "A human readable explanation for the additional metadata",
                "type": "string"
              }
            }
          },
          {
            "required": [
              "contentURL"
            ],
            "additionalProperties": false,
            "properties": {
              "name": {
                "description": "the name of the additional metadata",
                "type": "string"
              },
              "contentURL": {
                "description": "URL pointing to additional metadata",
                "type": "string"
              },
              "schemaURL": {
                "description": "A computer-readable schema for the additional metadata",
                "type": "string"
              },
              "aboutURL": {
                "description": "A human readable explanation for the additional metadata",
                "type": "string"
              }
            }
          }
        ]
      },
      "definitions": {
        "type": "object"
      },
      "parameters": {
        "description": "Parameters in dataset",
        "type": "array",
        "minItems": 1,
        "additionalItems": true,
        "uniqueItems": true,
        "items": {
          "type": "object",
          "required": [
            "name",
            "type",
            "units",
            "fill"
          ],
          "patternProperties": {
            "x_.*": {}
          },
          "additionalProperties": false,
          "properties": {
            "name": {
              "description": "Parameter name",
              "type": "string"
            },
            "type": {
              "description": "Parameter type",
              "oneOf": [
                {
                  "type": [
                    "string",
                    "object"
                  ],
                  "enum": [
                    "string",
                    "double",
                    "integer",
                    "isotime"
                  ]
                },
                {
                  "$ref": "/Ref"
                }
              ]
            },
            "units": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "/UnitsAndLabelCommon"
                }
              ]
            },
            "label": {
              "$ref": "/UnitsAndLabelCommon"
            },
            "length": {
              "description": "Number of characters in parameter (isotime and string parameters only)",
              "oneOf": [
                {
                  "type": "integer"
                },
                {
                  "$ref": "/Ref"
                }
              ]
            },
            "size": {
              "description": "Parameter size",
              "oneOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  },
                  "minItems": 1,
                  "minimum": 1
                },
                {
                  "$ref": "/Ref"
                }
              ]
            },
            "fill": {
              "oneOf": [
                {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                {
                  "$ref": "/Ref"
                }
              ]
            },
            "description": {
              "description": "a brief description of the parameter",
              "$ref": "/RefOrString"
            },
            "coordinateSystemName": {
              "description": "Some data represent directional or position information, such as look direction, spacecraft location, or a measured vector quantity. This keyword specifies the name of the coordinate system for these vector quantities. If a coordinateSystemSchema was given for this dataset, then the coordinateSystemName must come from the schema. See below for more about coordinate systems.",
              "$ref": "/RefOrString"
            },
            "vectorComponents": {
              "description": "The name or list of names of the vector components present in a directional or positional quanitity. For a scalar parameter, only a single string indicating the component type is allowed. For an array parameter, an array of corresponding component names is expected. If not provided, the default value for vectorComponents is ['x','y','z'], which assumes the parameter is an array of length 3.",
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "$ref": "/Ref"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "x",
                      "y",
                      "z",
                      "r",
                      "rho",
                      "latitude",
                      "colatitude",
                      "longitude",
                      "longitude0",
                      "other"
                    ]
                  },
                  "minItems": 1
                }
              ]
            },
            "bins": {
              "description": "Bins for components of a with a size having at least one element greater than 1",
              "oneOf": [
                {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "type": "object",
                    "anyOf": [
                      {
                        "required": [
                          "name",
                          "units",
                          "centers"
                        ]
                      },
                      {
                        "required": [
                          "name",
                          "units",
                          "ranges"
                        ]
                      },
                      {
                        "required": [
                          "name",
                          "units",
                          "centers",
                          "ranges"
                        ]
                      },
                      {
                        "required": [
                          "$ref"
                        ]
                      }
                    ],
                    "patternProperties": {
                      "x_.*": {}
                    },
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "description": "Name for the dimension (e.g., 'Frequency')",
                        "type": "string"
                      },
                      "$ref": {
                        "description": "JSON reference",
                        "type": "string"
                      },
                      "description": {
                        "description": "A brief comment explaining what the bins represent",
                        "oneOf": [
                          {
                            "type": "string"
                          },
                          {
                            "$ref": "/Ref"
                          }
                        ]
                      },
                      "units": {
                        "oneOf": [
                          {
                            "type": "string"
                          },
                          {
                            "$ref": "/Ref"
                          }
                        ]
                      },
                      "label": {
                        "oneOf": [
                          {
                            "type": "string"
                          },
                          {
                            "$ref": "/Ref"
                          }
                        ]
                      },
                      "centers": {
                        "description": "The centers of each bin.",
                        "oneOf": [
                          {
                            "type": "array",
                            "items": {
                              "type": "number",
                              "minItems": 1
                            }
                          },
                          {
                            "description": "The name of parameter with components that correspond the bin centers; use for time-varying centers",
                            "type": "string"
                          },
                          {
                            "description": "Any dimension not representing binned data should indicate this by using 'centers': null and not including the 'ranges' attribute.",
                            "type": "null"
                          },
                          {
                            "$ref": "/Ref"
                          }
                        ]
                      },
                      "ranges": {
                        "description": "The boundaries for each bin",
                        "oneOf": [
                          {
                            "type": "array",
                            "items": {
                              "type": "array",
                              "minItems": 1
                            }
                          },
                          {
                            "description": "The name of parameter with components that correspond to the bin ranges; This parameter must have size=[2,N], where N = size[i], where i is the dimension associated with the bin; use for time-varying bin ranges.",
                            "type": "string"
                          },
                          {
                            "$ref": "/Ref"
                          }
                        ]
                      }
                    }
                  }
                },
                {
                  "$ref": "/Ref"
                }
              ]
            }
          }
        }
      }
    }
  },
  "error": {
    "title": "error response",
    "description": "Server error response",
    "type": "object",
    "required": [
      "HAPI",
      "status"
    ],
    "patternProperties": {
      "x_.*": {}
    },
    "additionalProperties": false,
    "properties": {
      "HAPI": {
        "$ref": "/HAPI"
      },
      "status": {
        "$ref": "/HAPIStatus"
      }
    }
  }
}