vectorComponents clarification

hapi-dev/HAPI-data-access-spec-dev.md

@@ -799,8 +799,8 @@ The focus of the header is to list the parameters in a dataset. The first parame
 | `description`         | string               | **Optional** A brief, one-sentence description of the parameter.   |
 | `label`               | string OR array of string | **Optional** A word or very short phrase that could serve as a label for this parameter (as on a plot axis or in a selection list of parameters). It is intended to be less cryptic than the parameter name.  If the parameter is a scalar, this label must be a single string. If the parameter is an array, a single string label or an array of string labels are allowed.   `null` and the empty string `""` are not allowed. A single label string will be applied to all elements in the array, whereas an array of label strings specifies a different label string for each element in the array parameter. The shape of the array of label strings must match the `size` attribute, and the ordering of multi-dimensional arrays of label strings is as discussed in the `size` attribute definition above. See also the following example responses to an `info` query for examples of a single string and string array labels and additional details in [Units and Label Arrays](#3610-units-and-label-array).|
 | `stringType`          | string or object     | **Optional** A string parameter can have a specialized type. Currently, the only supported specialized type is a URI. See [The `stringType` Object](#366-stringtype-object) for more details on syntax and allowed values for `stringType`.  |
-| `coordinateSystemName`| string | **Optional** 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`](#364-coordinatesystemschema-details) was given for this dataset, then the `coordinateSystemName` must come from the schema. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for more about coordinate systems. |
-| `vectorComponents` | string or array of strings| **Optional**  The name or list of names of the vector components present in a directional or positional quantity. 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. There is an enumeration of allowed names for common vector components. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. |
+| `coordinateSystemName`| string | **Optional** Some parameters contain 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 quantities. If `coordinateSystemName` is given, `vectorComponents` should be given (but this is not required). If a [`coordinateSystemSchema`](#364-coordinatesystemschema-details) was given for this dataset, then the `coordinateSystemName` must come from the schema. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for more about coordinate systems. |
+| `vectorComponents` | string or array of strings| **Optional**  The name or list of names of the vector-related elements. For a scalar `parameter`, only a single string indicating its component type is allowed.  For an array `parameter`, an array of corresponding component names is expected.  If a parameter has a `coordinateSystemName` and three elements, and they represent Cartesian (x,y,z) values, then as a convenience, you may omit the `vectorComponents`.  For any other situation (not three elements, not Cartesian, not ordered as x,y,z), then you must specify the `vectorComponents` explicitly. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. |
 | `bins`                | array of Bins object | **Optional** For array parameters, each object in the `bins` array corresponds to one of the dimensions of the array and describes values associated with each element in the corresponding dimension of the array. The [bins object table](3611-bins-object) below describes all required and optional attributes within each `bins` object. For example, if the parameter represents a 1-D frequency spectrum, the `bins` array will have one object describing the frequency values for each frequency bin; within that object, the `centers` attribute points to an array of values to use for the central frequency of each channel, and the `ranges` attribute specifies a range associated with each channel. |
 
 **Example**
@@ -986,9 +986,9 @@ The `[1,2,3]` are measurements from the first instrument and the `[4, 5, 6]` are
 "label": [["V1x","V1y","V1z"],["V2x","V2y","V2z"]]
 ```
 
-### 3.6.11 vectorComponents Object
+### 3.6.11 `vectorComponents` Object
 
-For a `parameter` that describes a vector quantity (position of spacecraft relative to a body, location of ground station, direction of measured vector quantity, detector look direction), the `vectorComponents` keyword indicates the vector components present in the data.  For a scalar `parameter` that is associated with a vector component, this keyword contains a single string describing the component. For non-scalar parameters, this keyword contains an array of strings naming the coordinate values present in the parameter.
+For a `parameter` that describes a vector-related quantity (position of spacecraft relative to a body, location of ground station, direction of measured vector quantity, detector look direction), the `vectorComponents` keyword indicates the vector-related components present in the data.  For a scalar `parameter` that is associated with a vector component, this keyword contains a single string describing the component. For non-scalar parameters, this keyword contains an array of strings naming the coordinate values present in the parameter.
 
 The names represent the mathematical components typically found in vector or positional quantities. 
 
@@ -1003,10 +1003,12 @@ Possible component names are constrained to be one of the following:
 | `rho`          | Magnitude of radial component (perpendicular distance from z-axis) in a Cylindrical coordinate representation      |
 | `latitude`     | Angle relative to x-y plane from -90° to 90°, or -π to π (90° corresponds to +z axis)     |
 | `colatitude`   | Angle relative to +z axis, from 0 to 180°, or 0 to π |
-| `longitude`           | Angle relative to +x axis of a projection of the vector into the x-y plane, from -180° to 180°, or -π to π (90° corresponds to +y axis; this is also known as "East longitude") |
-| `longitude0`          | Angle relative to +x axis of a projection of the vector into the x-y plane, from 0° to 360°, or 0 to 2π (270° corresponds to -y axis; this is also known as "East longitude") |
-| `altitude`      | Altitude above a reference sphere or surface as identified in `coordinateSystemName`. For example, Earth's locations are often described by longitude, latitude, and altitude.|
-| `other`             | Any parameter component that cannot be described by a name in this list |
+| `longitude`    | Angle relative to +x axis of a projection of the vector into the x-y plane, from -180° to 180°, or -π to π (90° corresponds to +y axis; this is also known as "East longitude") |
+| `longitude0`   | Angle relative to +x axis of a projection of the vector into the x-y plane, from 0° to 360°, or 0 to 2π (270° corresponds to -y axis; this is also known as "East longitude") |
+| `altitude`     | Altitude above a reference sphere or surface as identified in `coordinateSystemName`. For example, Earth's locations are often described by longitude, latitude, and altitude.|
+| `other`        | Any parameter component that cannot be described by a name in this list |
+
+Note that `vectorComponents` should be interpreted as describing vector-related elements. In some instances, the `vectorComponents` will describe a proper vector (e.g., if `vectorComponents = ["x", "y", "z"]`).
 
 Many angular quantities in datasets have different names than the ones here
 (azimuth instead of longitude, or elevation or inclination instead of latitude),