# Copyright (c) 2020 Contributors to the Eclipse Foundation
#
# See the NOTICE file(s) distributed with this work for additional
# information regarding copyright ownership.
#
# This program and the accompanying materials are made available under the
# terms of the Eclipse Public License 2.0 which is available at
# http://www.eclipse.org/legal/epl-2.0
#
# SPDX-License-Identifier: EPL-2.0
name: fields
in: query
description: |-
  Contains a comma-separated list of fields from the properties to be
  included in the returned JSON.

  #### Selectable fields

  Supports selecting arbitrary sub-fields as defined in the properties by
  using a comma-separated list:
    * several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)

      For example:
        * `?fields=temperature` would select only `temperature` property value (if present)
        * `?fields=temperature,humidity` would select only `temperature` and `humidity` property values (if present)

  Supports selecting arbitrary sub-fields of objects by wrapping sub-fields
  inside parentheses `( )`:
    * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
    * sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield

      For example:
       * `?fields=location(longitude,latitude)` would select the `longitude` and `latitude` value inside the `location` property

  #### Examples

  * `?fields=temperature,humidity,location(longitude,latitude)`

  * `?fields=configuration,status(powerConsumption/watts)`
required: false
schema:
  type: string