.. _user/services/structure/metadata:

********
metadata
********

The *metadata* section allows you to specify further information about
your service in a structured way.

  .. Metadata Keys
  .. =============

  .. name
  ..   A short title typically used in UI representation

  .. icon
  ..   A link to an icon image typically used in UI representation

  .. provider
  ..   The provider/author of the this service commissioning file

  .. homepage
  ..   URL to the homepage of the provider

Properties
==========

=========== ========== ============
Property    Type       Required
=========== ========== ============
`homepage`_ ``string`` Optional
`icon`_     ``string`` Optional
`name`_     ``string`` **Required**
`provider`_ ``string`` Optional
`version`_  ``string`` Optional
=========== ========== ============


homepage
--------

URL to the homepage of the provider

- is optional
- type: ``string``
- format: ``uri`` – Uniformous Resource Identifier (according to `RFC3986`_)


icon
----

A link to an icon image typically used in UI representation

-  is optional
-  type: ``string``


.. _user/services/structure/metadata/name:

name
----

A short title typically used in UI representation.

It is allowed to use :ref:`parameter substitutions
<user/services/structure/parameters>` in this property, for example setting it
to ``!sub 'Machine ${machineNum}'`` if there exists a parameter `machineNum`.

The auto-generated default :ref:`Service ID <user/services/service-id>` will be
generated from this string by removing all characters that are not allowed for
the Service ID. For backward-compatibility reasons, in Connectware version 1.0.x
all characters are changed to lowercase and also all punctuation is removed,
including underscore and period.

- required
- type: ``string``

  - maximum length: 80 characters


provider
--------

The provider/author of the this service commissioning file

- is optional
- type: ``string``


version
-------

Semantic version of the service

- is optional
- type: ``string``


.. _homepage: #homepage
.. _icon: #icon
.. _name: #name
.. _provider: #provider
.. _version: #id1
.. _RFC3986: http://tools.ietf.org/html/rfc3986



Example
=======

.. code-block:: yaml

  metadata:
    name: Simulated Machining Center
    icon: http://www.axon-mcs.de/wp-content/uploads/2016/08/Litz-LU620.jpg
    provider: cybus
    homepage: https://www.cybus.io