2.0/openapi/sources/parameters/thingFieldsQueryParam.yml

# 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 to be included in the returned
  JSON. attributes can be selected in the same manner.

  #### Selectable fields

  * `thingId`
  * `policyId`
  * `definition`
  * `attributes`

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

        For example:
          * `?fields=attributes/model` would select only `model` attribute value (if present)
          * `?fields=attributes/model,attributes/location` would select only `model` and
             `location` attribute 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=attributes(model,location)` would select only `model`
            and `location` attribute values (if present)
         * `?fields=attributes(coffeemaker/serialno)` would select the `serialno` value
            inside the `coffeemaker` object
         * `?fields=attributes/address/postal(city,street)` would select the `city` and
            `street` values inside the `postal` object inside the `address` object

  * `features`

    Supports selecting arbitrary fields in features similar to `attributes` (see also features documentation for more details)

  * `_namespace`

    Specifically selects the namespace also contained in the `thingId`

  * `_revision`

    Specifically selects the revision of the thing. The revision is a counter, which is incremented on each modification of a thing.

  * `_created`

    Specifically selects the created timestamp of the thing in ISO-8601 UTC format. The timestamp is set on creation of a thing.

  * `_modified`

    Specifically selects the modified timestamp of the thing in ISO-8601 UTC format. The timestamp is set on each modification of a thing.

  * `_metadata`

    Specifically selects the Metadata of the thing. The content is a JSON object having the Thing's JSON structure with the difference that the JSON leaves of the Thing are JSON objects containing the metadata.

  * `_policy`

    Specifically selects the content of the policy associated to the thing. (By default, only the policyId is returned.)

  #### Examples

  * `?fields=thingId,attributes,features`
  * `?fields=attributes(model,manufacturer),features`
required: false
schema:
  type: string