2.3. Object models

The object models define how the content of the information exposed is formatted based on the semantics of the information. The models are organized along categories that define the operational state of the facility:

The Device model defines the digital ‘population’ that communicates and interacts in the facility
The Space model defines the geographical environment of the facility
The Event model defines the changes happening in the ecosystem, whether in the devices, the environment, or the operations
The Tag model defines logical organizations and groupings

Note

Other models such as a Task model that will define the activities and scheduled operations in the facility will be added in future versions with the aim to complete the definition of the operational state of the facility

2.3.1. Definitions

Common definitions

2.3.1.1. Model

Object Model

The structured and human-readable description of the information being exchanged between the information provider and consumer.: The information about this soap dispenser is described in the object model of dispenser devices

Property

The semantic description of a piece of information.: The device_type property for the soap dispenser is ‘dispenser’

Value type

The JSON data representation of the information contained in the property. Note that the value of a property can also be an object.: The value type of the device_type property is a string

Object

A logical grouping of properties: the geolocation object contains the longitude and latitude properties

Item

A digital set of information linked together and identified by an ID. In this context, an item can be a device, a space, a tag, or a message: We know this is a device item because it is represented by a device ID

2.3.1.2. Device

Model

The manufacturer ‘s commercial name of a device: Clean Inc. introduced a new model in its scrubber family: the S200

Serial Number

A series of characters assigned by a manufacturer that uniquely identify a device specifically for this manufacturer: The serial number of this S200 machine is S200-112

Production Date

The date the device ID has been assigned by the manufacturer: The device was produced and entered in the manufacturer ‘s database as a production date of June 3rd, 2019

Registration Date

The date the device is assigned to and can be accessed by a resource owner: The customer bought the device on September 10th, 2019 which is also the registration date for accessing this device’s data

Last Contact

The date and time the device has last established a communication with the system: The last contact with the device was as planned at 23:30 yesterday

Start Connectivity Date

The date a device has sent the first communication: The start connectivity date was 2 months after the registration date

Statistic Date Range

The date-time range specified by the user between which the user is requesting statistic information about devices: The supervisor would like to know how the device was used during the statistic date range between 7:00 and 17:00 last Monday

Aggregation Start Date

The starting date-time specified by the user in the statistic date range: When requesting monthly information for January, please specify January 1st, 00:00 as an aggregation start date…

Aggregation End Date

The end date-time specified by the user in the query date range: …And January 31st, 23:59 as an aggregation end date

Expected Next Service

The date-time of the next expected prognostic or predictive analysis: The battery on this dispenser should be replaced during the expected next service on June 1st

Error Code

A series of characters that uniquely identifies the reason a machine is defective

The overheat error code means that the drive motor needs to be replaced
the communication_error means that the dispenser has not been communicating for a week

Device Threshold

A threshold that will trigger a communication event: The dispenser sent a notification when the device threshold for the filling level reached 20%

Battery Health

The health condition of a battery: The battery health indicates that it is reaching its end of life

Battery Level

The percentage of remaining battery capacity

At the end of the shift, the battery level was 25%
The fixed equipment device battery level is 80%

Battery Level Timestamp

The date-time the battery level was last reported by the machine: The battery level reported was recorded by the machine with a battery level timestamp of 15:30

Battery Remaining Life

The expected or predicted remaining life of the battery in percent before it must be replaced: The battery remaining life is now less than 10% and should be replaced

Signal Strength

The quality of the wireless signal at the device level: The signal strength of this device is barely enough to establish communication

Signal Level

The quality of the wireless signal at the device level measured in number of bars from 0 to 4

0 means no signal
4 means excellent signal

The signal level reported is 3 bars meaning that there is a good connectivity

Wireless Technology

The type of wireless signal used to provide data by the device. It can be:

WiFi
2G
3G
4G
5G
LTE
LTE_m
Bluetooth 4.1
Bluetooth 4.2
Bluetooth 5
BLE
LORA
Wirepas
ENOCEAN
RFID
NB IOT

This device has a 4G modem for communication

Signal Strength Threshold

The minimum signal strength considered necessary to guarantee the quality of the data transmission: The signal strength threshold should be at -100dBm to ensure connectivity

2.3.1.3. Space

Space Name

A human readable description of a space that localizes the space in its physical environment: The Men’s bathroom on the second floor of the office building is the name of the space representing a specific toilet

Part of

The parent space that contains the space being described: The bathroom is part of the the second floor space, which itself is part of the office building space

Composed of

The one or multiple spaces that are contained within the space being described: The second floor space is composed of an entrance space, 5 office spaces, and one bathroom space

2.3.1.4. Message & Event

Message

A piece of information about an entity (device or space) that is communicated to the information consumer and initiated by the information provider: The bin manufacturer provided a message about the new filling level of the trash can in the entrance of the building

Event

A trigger that changes the state of an entity: The dead battery is the event that triggered the dispenser to stop working

Alert

An actionable event that requires external intervention (usually human intervention) to change the state of the entity: The alert informed the janitor to refill the empty soap dispenser

Notification

An event that does not require immediate external intervention and that informs about the new state of the entity: The cleaning supervisor is waiting for a notification that the cleaning machine is operational again following a service intervention

Status message

A message about the current state of an Entity: The latest status message about the soap dispenser indicated that it is 75% full

Diagnostic message

A message about a predicted future state of an entity: The diagnostic message indicated that the trash can will be full in two days

Message category

The characterization of a message being provided. It can be one of

“alert”
“notification”
“status”
“diagnostic”

The category of this event is an alert

Message code

A language independent and semantically descriptive short string summarizing the meaning of the message or event.: out_of_order is a message code indicating that the device is not operational

Message timestamp

The date and time the trigger for the message happened: The machine became unavailable on June 1st, 2021 at 22:34:10 which triggered an out_of_order alert

2.3.1.5. Tag

Tag

A digital label attached to an entity such as device and/or space that identifies its belonging to a group: The ‘Public Bathroom Faucets’ is a tag for all faucets located in the public bathrooms of the hotel

Tag Type

The intent of the tag. It must be ‘organization_grouping’: The intent of the ‘Public Bathroom Faucets’ tag is to logically organize faucets that need frequent cleaning. Therefore the tag type is organization_grouping

Tag ID

A series of characters that uniquely identify a tag across the digital world: The tag ID of the ‘Public Bathroom Faucets’ tag is ‘fb9e9c4f-3230-4886-bbaf-c141066f7d04’

2.3.1.6. Error

Protocol error

An error that occurs at the communication protocol level between the information consumer and the information provider: The device manufacturer return an error because the Web API request had an invalid query parameter name

Item error

An error that occurs when the information provider cannot provide information for a specific item: The soap dispenser manufacturer returned an item error because the device ID provided is not known

Error code

A pre-defined numeric value describing a category of protocol error: 400 is the defined HTTP error code for bad formatted requests

Error message

A language independent and semantically descriptive short string summarizing the meaning of the error.: invalid_parameter is an error message indicating that a parameter was invalid in a request for information

2.3.2. FDS compliance requirements

2.3.2.1. The core structure

All object models must follow the same item root structure

an ID that uniquely identifies an item (device, space, message, or tag) across the digital world
a generic object that contains properties that are common to an item (device type, space type, message code, or tag)
- the generic object is required
- Properties in the generic object must always be required
  For example, every device has a manufacturer that must be exposed
a specific object that contains properties that only apply to a specific type of an item (device type, space type, message code, or tag type)
- the specific object is optional
- Properties in the specific object can be required or optional
  For example, trash bins are a type of device that have specific information such as the bin volume

When representing information for a collection of items, the object model must follow the collection root structure

a data property that contains an array of item objects
- The item object depends on the structure of the information being represented
  For example, when retrieving the status of a collection of devices, the item object is a status object
an errors property that contains an array of item_error objects for each item containing an error
Information about an item must be in only one of the data array or errors array
an optional count property that contains the number of items in the data array

2.3.2.2. Properties

Properties must follow the JSON key-value pair definition.
Some of the properties can be defined as objects, allowing for a hierarchical object model structure

2.3.2.2.1. Required properties

Required properties must always be included in the response with a valid value.
If a provider is unable to expose a required property, then the 500 HTTP status code must be returned, and the response must contain an ‘error ‘ object which must contain a message clearly identifying the data that is not available.

2.3.2.2.2. Optional properties

If a data provider does not expose an optional property, or if the data is not available for any reasons at the time of the request, the property must not be included in the response.

For example, a ‘specification’ object model for a device type has the following required and optional properties:

{
    device_id: required
    generic: required
        device_type: required
        manufacturer: required
    device_type_specific: optional
        country: optional
        production_date: optional
}

Case 1: the provider exposes the optional data

{
    "device_id": "CLEANINC_C1_1234",
    "generic": {
        "device_type": "cleaning_machine",
        "manufacturer": "Clean Inc."
    },
    "device_type_specific": {
        "country": "USA",
        "production_date": "2020-02-15T00:00:00Z"
    }
}

Case 2: the provider doesn’t expose the optional data

{
    "device_id": "CLEANINC_C1_1234",
    "generic": {
        "device_type": "cleaning_machine",
        "manufacturer": "Clean Inc."
    }
}

Case 3: the provider exposes the optional data but production_date is not available

{
    "device_id": "CLEANINC_C1_1234",
    "generic": {
        "device_type": "cleaning_machine",
        "manufacturer": "Clean Inc."
    },
    "device_type_specific": {
        "country": "USA"
    }
}

2.3.2.3. Unique ID

All entities (device, space, event, tag) must be identifiable by a unique ID using Universally Unique Identifiers as defined in standard ISO/IEC 9834-8 (Information technology — Procedures for the operation of object identifier registration authorities — Part 8: Generation of universally unique identifiers (UUIDs) and their use in object identifiers)

This applies to:

Device IDs
Space IDs
Event IDs
Tag IDs

Attention

FDS Version 1 defined a different format for Device IDs:

The device ID must be formed by the concatenation of
- The manufacturer
  
  String of at least 3 characters
- The model
  
  String of at least 2 characters
- The serial number
  
  String of at least 1 character
The device ID must follow the format
- “<manufacturer>_<model>_<serial number>”

Devices defined in FDS version 1 will work in FDS version 2. All new devices defined using FDS version 2 shall use the UUID definition.

2.3.2.4. Errors

The following diagram provides an overview of the error and item_error objects.

Error information related to an error in the communication protocol must be provided in the error object
Every error must contain the status code
The status code must be one of
- 204
- 400
- 401
- 403
Every error must contain a language-independent descriptive message
The descriptive message must be one of
- “not_implemented”
- “unauthorized_request”
- “invalid_parameter”
- “duplicate_parameter”
- “missing_parameter”
- “invalid_parameter_combination”
- “invalid_date”
- “invalid_start_date”
- “invalid_end_date”
- “missing_device_locations”
- “duplicate_devices”
- “missing_tag”
- “invalid_tag”
- “invalid_tag_object”
- “invalid_entities”
- “tag_already_exists”
- “invalid_associations”
- “over_limit”
For example, a request to get device specifications since January 1st 2021 with an invalid date format would return an error object similar to:

{
    "status": 400,
    "message": "invalid_date",
    "additional_info": "not_iso_8601_compliant"
}

Error information related to an item (device, space, message, tag…) must be provided in the item_error object
Every item error must contain the ID of the item
Every item error must contain the type of the item
The item type must be one of
- “device”
- “space”
- “message”
- “message_code”
- “tag”
Every item error must contain a language-independent descriptive message
The descriptive message must be one of
- “invalid_device”
- “invalid_tag”
- “invalid_space”
- “invalid_message_code”
- “invalid_location”
- “duplicate_devices”
- “already_assigned”
- “not_assigned”
For example, a request to get device statuses for 2 device IDs known by the information provider and 2 unknown device IDs would return:

{
    "data": [
      {
        "<status object>"
      },
      {
        "<status object>"
      }
    ],
    "errors": [
      {
        "item_id": "0312c7a7-1e59-5990-7ed7-e99535f3826d",
        "item_type": "device",
        "message": "invalid_device"
      },
      {
        "item_id": "22850fd0-2871-3813-832f-4f73abf0857f",
        "item_type": "device",
        "message": "invalid_device"
      }
    ],
    "count": 2
}

2.3.2.5. Images

Information about images that can be displayed in a browser environment must be provided in the image Object.

The following diagram provides an overview of the image and device_image objects.

Every image must contain a public url of the location of the image
When provided, the content type of the image must be one of
- “jpg”
- “png”
- “pdf”
- “gif”
- “bmp”
- “png”
Images about a device must be provided in the device_image object
A device image must contain an image object with the path of the full size image

The detailed API specifications for each object can be found in the reference chapter.

2.3.2.6. Geolocation

Information about geolocation (longitude and latitude) of an entity (device or space) must be provided in the geolocation object.

The following diagram provides an overview of the geolocation and device_geolocation objects.

The geolocation object must comply to the GeoJSON format defined in (RFC 7946)
- the type must be “Point”
- the coordinates must be an array of two elements.
  - The first element must be the longitude
  - The second element must be the latitude
For example

{
    "type": "Point",
    "coordinates": [-93.3131726, 44.9138571]
}

Geolocation of a device must be provided in the device_geolocation object
A device geolocation must contain a geolocation object
A device geolocation can provide an accuracy and timestamp information
For example, a mobile device can provide its geolocation within a 100m radius accuracy:

{
    "geolocation": {
      "type": "Point",
      "coordinates": [-93.3131726, 44.9138571]
    },
    "geolocation_accuracy": {
      "not_better_than": 0.1,
      "not_worse_than": 100.0
    },
    "geolocation_timestamp": "2021-02-25T23:45:23Z"
}

The detailed API specifications for each object can be found in the reference chapter.

2.3.2.7. Health Status

The health status of a device or a component of a device is provided in the health object.

The following diagram provides an overview of the health object.

The health status must be one of
- “operational”
- “maintenance_required”
- “defective”
- “unknown”
Additional information can be provided in the health_details array. When defined, the health details must be one or multiple message codes as defined in the event Model
The following example shows the health status of a device no longer operational because it got damaged by an impact and the battery reached its end of life

{
  "health_status": "defective",
  "health_timestamp": "2021-02-25T23:45:23Z",
  "health_details": ["impact", "critical_battery_level"]
}

The detailed API specifications for each object can be found in the reference chapter.

2.3.2.8. Battery Information

Information about battery systems in a device is provided in the battery object.

The following diagram provides an overview of the battery object.

This object applies for both non-rechargeable and rechargeable battery systems
For rechargeable batteries, information about the last charge cycle can be provided in the charge Object
The following example shows the minimum battery status information for a non-rechargeable Battery

{
  "battery_level": 0.9,
  "battery_timestamp": "2021-02-25T23:45:23Z"
}

The following example shows the status of a rechargeable battery that reached its end of life

{
  "battery_level": 0.5,
  "battery_timestamp": "2021-02-25T23:45:23Z",
  "battery_health": {
    "health_status": "maintenance_required",
    "health_timestamp": "2021-02-25T05:20:00Z",
    "health_details": ["impact", "critical_battery_level"]
  },
  "battery_last_charge": {
    "charge_cycle": 769,
    "last_charge_initial_level": 0.1,
    "last_charge_final_level": 1.0,
    "last_charge_start_time": "2021-02-25T05:03:00Z",
    "last_charge_end_time": "2021-02-25T05:20:00Z"
  }
}

The detailed API specifications for each object can be found in the reference chapter.

2.3.2.9. Signal Information

Most devices communicate their data through a wireless mechanism. Signal information is provided in the signal object.

The following diagram provides an overview of the signal object.

The signal strength, or the signal level, or both must be provided
- If the signal strength is not being reported, then the signal level must be provided
- If the signal level is not being reported, then the signal level must be provided
When provided, the signal technology must be one of:
- “wifi”
- “2g”
- “3g”
- “4g”
- “5g”
- “lte”
- “lte_m”
- “bluetooth_4.1”
- “bluetooth_4.2”
- “Bluetooth_5”
- “ble”
- “lora”
- “wirepas”
- “enocean”
- “rfid”
- “nb_iot”
The following example shows the signal information for a device communicating through 4G

{
  "signal_strength": -32.0,
  "signal_level": 3,
  "signal_timestamp": "2021-02-25T23:45:23Z",
  "signal_technology": "4g"
}

The detailed API specifications for the signal object can be found in the reference chapter.

2.3.2.10. Usage Variation Recordings

When reporting dynamic information with large variation between two readings, such as power usage, motor RPM, or device temperature, information providers can use the generic variation_recording object.

The following diagram provides an overview of the geolocation and device_geolocation objects.

../_images/variation_recording_object_model.png

Because the object is generic, the variation recording must provide the unit of the recording

The supported units are

Recording	Unit
distance	“m”
surface	“m2”
volume	“m3”
temperature (degrees Celsius)	“celsius”
voltage (Volt)	“v”
current (aAmp)	“a”
power consumption (Watt)	“w”
Energy consumed (Watt-Hour)	“wh”
Motor speed (RPM)	“rpm”
Pressure (Pascal)	“pa”

the last reading and the timestamp of the last reading must be provided
The information provider can also specify the minimum and maximum readings in the last 24 hours, along with the average value over a 24 hours period
The following example shows the device internal temperature Recordings

{
  "unit": "celsius",
  "last_reading": 22,
  "last_reading_timestamp": "2021-02-25T23:45:23Z",
  "average_24h": 20,
  "max_24h": 30,
  "min_24h": 10
}

The detailed API specifications for each object can be found in the reference chapter.

2.3.2.11. The Device Model

The following diagram provides an overview of the Device Model

Every device must be associated to a device type
The device type must be one of
- “cleaning_machine”
- “dispenser”
- “bin”
- “waste_station”
- “smart_handle”
The object model for all device types depends on the type of information exposed
- Static information throughout the life of a device must be exposed in the specification object
- Dynamic information about the latest known state of the device must be exposed in the status object
- Aggregated historical information of a device must be exposed in the statistic object
- Predictive information about a device must be exposed in the diagnostic object
The specification, status, statistic, and diagnostic objects must follow the item core structure
- The content of the generic object is defined for each of these objects
- The content of the specific object is defined at the device type level
A collection of specification, status, statistic, or diagnostic objects must follow the collection core structure
- The item object for a collection of specifications must be the specification object
- The item object for a collection of statuses must be the status object
- The item object for a collection of statistics must be the statistic object
- The item object for a collection of diagnostics must be the diagnostic object
Errors related to exposing information about a specific device must be exposed in a item_error object
- The item type in the item_error object must be “device”

The detailed API specifications for each object can be found in the reference chapter

2.3.2.12. The Space Model

2.3.2.12.1. Physical environment

The space information must be exposed through the space object.

The following diagram provides an overview of the Space Model

Every space must be associated to a space type
The space type must be one of
- “site”
- “building”
- “floor”
- “suite”
- “room”
- “restroom”
- “toilet”
- “hallway”
- “corridor”
- “aisle”
- “cubicle”
- “section”
The space object must follow the item core structure
- The content of the specific object is defined at the space type level
The creation date must be the date the space was built or defined
- For example, if a site first became operational in May 2010, with only one building, then the creation date will be May 2010 for all spaces.
- If a new building was completed in October 2011, then the creation date will be October 2011 for this building and all spaces in the building.
- If a floor in a building has been remodeled in July 2012, then all the new spaces on that floor will have a creation date of July 2012, but the floor itself will maintain its original creation date.
The space model must define a hierarchical tree structure of the physical environment
- a space must be part of one and only one larger space
- a space must be composed of one or multiple smaller spaces
A space object must provide the full upward hierarchy to represent a space in the context of the full physical environment
- The upward hierarchy must be exposed through the space_chain object
A special self-contained space object representing a void must be exposed
- the space ID must be “00000000-0000-0000-0000-000000000000”
- the space type must be “nothing”
- the nothing space must be part of nothing
- the nothing space must be composed of nothing

{
    "space_id": "00000000-0000-0000-0000-000000000000",
    "generic": {
        "space_type": "nothing",
        "name": "nothing",
        "part_of": {
            "space_id": "00000000-0000-0000-0000-000000000000",
            "space_type": "nothing"
        }
    }
}

The top level space in the hierarchical tree must be part of nothing
The lowest (most granular) space in the hierarchical tree must be composed of nothing
When one or multiple devices are associated to a space, the space object must define the “contains_devices” property in the space type specific object
A collection of space objects must follow the collection core structure
- The item object for a collection of spaces must be the space object
Errors related to exposing information about a specific space must be exposed in the item_error object
- The item type in the item_error object must be “space”

The detailed API specifications for each object can be found in the reference chapter.

2.3.2.12.2. Device Location

The relationship between a device and the space where it is located must be exposed through the device_location object.

A collection of device locations must follow the collection core structure
- The item object for a collection of device locations must be the device_location object
Errors related to exposing information about a specific device location must be exposed in the item_error object
- The item type in the item_error object must be “device”

2.3.2.13. The Event model

The following diagram provides an overview of the Event Model.

The event information must be exposed through the message object
Every event must have an “alert” or “notification” category
Every event must be associated with an entity ID (device ID or space ID)
Every event must be associated with the entity type (all supported device types and all supported space types)

Every event must be associated with a message code

The message code must be one of:

Message code	Description	Message category	Message code specific object
out_of_order	The device is out of order and needs service intervention	alert	out_of_order_details property - array of information provider codes
out_of_order_recovery	The device is operational again following an out of order problem	notification	correlation_id property - UUID of out of order event
regular_maintenance	The device is due for its regular maintenance service	notification	None
regular_maintenance_completed	The regular device maintenance was performed	notification	correlation_id property - UUID of regular maintenance event
impact	An impact on the machine was detected	notification	None
opportunity_charging	An opportunity charging of a lead acid battery has been detected (battery not fully charged)	notification	opportunity_charge - Charge object
low_battery_level	The device has a low battery level and needs to be recharged or replaced soon	notification	battery_level property
critical_battery_level	The device battery level is critically low and will no longer be operational	alert	battery_level property
offline	The device is not communicating	notification	last_contact property
charging_cycle_started	The device has been put on charge	notification	charging_cycle property
charging_cycle_stopped	The device has been disconnected from the charger, or the charger provided an end of charge signal	notification	battery_level property
power_on	The device has been powered on and is operational	notification	None
bin_overflow	The bin is more than 100% full	alert	None
mold_detected	Mildew or mold has been detected	alert	None
low_wireless_signal	A low wireless signal has been detected	notification	signal_strength property

The list of supported message codes within the list of possible codes must be defined at the entity (device, space) type level

The message object must follow the core structure
- The content of the specific object is defined at the message code level
A collection of messages must follow the collection core structure
- The item object for a collection of messages must be the message object
Errors related to exposing information about a specific message must be exposed in the item_error object
- The item type in the item_error object must be “message”
When an information provider supplies detailed information about a message code, the detailed information must be exposed through the event_specification object
The detailed information must contains at least a description of the message code
Any detailed information is language-dependent and must be provided in at least one language.
The information in each language must be exposed through the locale object
When access to external resources is provided as part of the detailed information, the external resource information must be exposed through the resource object
Detailed information for a collection of message codes must follow the collection core structure
- The item object for a collection of messages must be the event_specification object
Errors related to exposing information about a specific message code must be exposed in the item_error object
- The item type in the item_error object must be “message_code”

The detailed API specifications for each object can be found in the reference chapter.

2.3.2.14. The Tag model

The following diagram provides an overview of the tag Model.

the tag information must be exposed through the tag object
Every tag must be associated to a tag type
- the “organization_grouping” must be the only type defined
A tag must apply to one or multiple entities (devices and/or spaces)
A collection of tags must follow the collection core structure
- The item object for a collection of messages must be the tag object
Errors related to exposing information about a specific message must be exposed in the item_error object
- The item type in the item_error object must be “tag”

The detailed API specifications for the tag object can be found in the reference chapter.

2.3.3. Use case example

Note

Join FDS to get access to examples and use cases.