Site
====

A site is the highest level in the hierarchical tree describing a physical environment.

- A site is composed of one or multiple buildings
- Some devices can be associated at the site Level

  - For example, a fleet of floor cleaning machines can be associated to a site if no machines always clean the same building
  - As another example, a people counter can be installed at the main entrance of fenced-in campus of a company with multiple buildings

- A site belongs to an owner entity.
  
  - In the case of a private site, the owner entity is the company or person that owns the site

    - For example, the Microsoft headquarters site in Redmond, Washington, is owned by Microsoft and contains 83 buildings.

  - In the case of a public site, like a government site or public university, the owner entity is an administration, such as a city or state. 

    - For example, the National Mall in Washington DC is a site that includes many museums, is administered by the US federal government as its owner entity.


FDS compliance requirements
---------------------------

Object Model
''''''''''''

Space object for the site space type 
""""""""""""""""""""""""""""""""""""

- The space type in the generic space object must be

  - "site"

- The digital twin information provider must provide a **space** object that contains a **space_type_specific** object defined in the following diagram

.. figure:: ../../_static/site_object_model.png
    :width: 100%

- The **address** object must follows Apple's (`Indoor Mapping Data Format <https://docs.ogc.org/cs/20-094/Address/index.html>`__) specifications
- When the digital twin information provider provides additional information about the site, the composed_of property must be an array representing the list of buildings in the site.

  - The type of the space objects represented by the list of space IDs must be "building"

- A site space cannot be part of another space
  
  - The part_of property in the space generic object must refer to the void space_chain object

.. code-block:: json

    {
        "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 detailed API specifications for each object can be found in the `reference <../reference>`__ chapter.

Web API (Pull Model)
''''''''''''''''''''

- The digital twin information provider must implement the Web API as defined in the `pull model specifications <../communication_model/pull_model/physical_environment>`__


Publish/Subscribe (Push model)
''''''''''''''''''''''''''''''

.. note::

    No publish/subscribe messages related to digital twin information are defined in FDS Version 2

Use case example
----------------

.. include:: ../../common/use_case_site_space.rst