Best practice for 'name' properties

[jeremy303]

I've assumed that the Thing.name property is intended primarily as a label to be read by humans, however I have seen many examples of snake-case formatted name values, e.g. some_identifier, suggesting that some applications of STA intend the values to be read by machines. Would someone kindly clarify the primary audience for this value? It's people, right?

Related, in our application of STA, as I expect with many others, we require that Things have an ID that is independent of the ID auto-generated by the STA server. Our options are to use Thing.name to record this value or add an entry to Thing.properties, e.g. 'appId'. I'm assuming this latter approach would be the preferred approach, design wise? However it does seem that it's less than ideal to to create a database index on Thing.properties just to support such queries.

Thanks!

[mjacoby]

The standard document is rather clear about the intended use for

Thing.name

A property provides a label for Thing entity, commonly a descriptive name.

and Thing.description

This is a short description of the corresponding Thing entity.

For my understanding, this means it should be a human-readable name. An open issue here is the missing support for multiple languages.

Regarding of the use of externally created IDs I can say that this has been brought up a while ago in the issues of FROST-Server (https://github.com/FraunhoferIOSB/FROST-Server/pull/49). We ended up accepting a pull request that allows IDs to be set by the user, so with FROST-Server implementation of STA you can currently do what you need. However, this is not 100% compliant with the standard as it says

id is the system-generated identifier of an entity. id is unique among the entities of the same entity type in a SensorThings service.

This means the standard forces the id property to be auto-generated by the server. Maybe this is not the best idea and should be reconsidered. However, it might add more complexity to the standard than expected because of special cases that might occur e.g. in batch processing.

Currently, if you want to be 100% compliant to the standard then the only way is using Thing.properties with some custom-defined key just like you said (which probably results in horrible response time when filtering/searching by this).

[taniakhalafbeigi]

Thing's name and description are for recording metadata about the Thing and you can decide for your use case what makes sense to put in description and name. Sometimes the identifier is actually the name. We have an air quality system use case and actually the serial number of the device is the best name for us. I think name is the label for that Thing as said in the standard itself, how you label you Thing is really depending on the use case. This name might be what used by the client as label to show that Thing on a chart or map for example, this is how you can think of it. Again in some cases you find out that you actually want that custom identifier to be the label and in that case I think there is no harm for using name property for storing the custom identifier.

[hylkevds]

Name should be human readable, but in some cases there is no human readable name, so then we just put the mac address in the name.

If a proper human readable name does exist, that leaves the question of where to put machine readable Identifiers. Some options are:

• in name, pre/post-fixed to the human readable name.
  • Advantage: every server implementation supports filtering on that, using the string functions.
  • Disadvantage: it's ugly, and makes indexing at database level harder.
• as property. Since you can put anything in the properties, a machine readable ID can also go there.
  • Advantage: clean, efficient, searchable.
  • Disadvantages:
  • Not all servers support filtering on properties
  • There is no standard, so every use-case uses a different property name
• as @iot.id
  • Advantage: it's the place for machine readable ids
  • Disadvantage:
  • It's supposed to be system generated, most server implementations do not allow client-generated ids
  • Most server implementations only allow integer ids
  • If the id has slashes in it (like in URLs), then the selfLinks become problematic

It would be nice if all entities had an "identifier" field, or if a JSON-LD like document exists that describes the structure of the properties, so that clients can find the machine readable identifier.