Refine definition of Discoverer

[benfrancis]

I've noticed that the definition of "Discoverer" in WoT Architecture 1.1 is inconsistent with the way the term is used in the WoT Discovery 1.1 specification.

WoT Architecture section 3 defines a "Discoverer" as:

An entity that generates and registers a TD with an exploration service on behalf of a Thing which may not be able to do it for itself.

WoT Discovery section 5 says:

We will use the term Discoverer for an entity that is a client of the WoT Discovery process. A Discoverer may or may not be a full Consumer. A Discoverer does however need to read and extract information from special TDs for Directories and Thing Links and use specific affordances and links provided in them.

The definition in WoT Architecture only seems to cover the registration of TDs with an exploration service (a role perhaps more accurately described as a "registrant"), whereas section 3 of WoT Discovery goes on to describe many other functions such as:

1. Supporting at least one introduction mechanism
2. Fetching TDs from URLs as part of the introduction process
3. Merging/de-duplicating URLs from different introduction mechanisms
4. Distinguishing Thing Discription Directories from Thing Links
5. Consuming the Directory Service API
6. Recursively following Thing Links

A more accurate definition might therefore be:

"An entity which acts as a consumer of a WoT Discovery service, e.g. to discover and fetch a Thing Description, search a Thing Description Directory or register a Thing Description with a Thing Description Directory."

While I'm on this topic, I know there has been a lot of discussion around this already but I still think the term "Discoverer" (apart from not being a real word in the English language) is a confusing term for an entity which also registers a TD. A potential alternative term could be "Discovery Agent" (or "Discovery Client", "Discovery Consumer).

[egekorkan]

I would prefer the above-proposed definition, maybe adding the Introduction and Exploration type would be good, so something like:

"An entity which acts as a consumer of a WoT Discovery service via an introduction or exploration mechanism, e.g. to discover and fetch a Thing Description, search a Thing Description Directory or register a Thing Description with a Thing Description Directory."

I think we should simply link to the discovery chapter as well.

I would also prefer the Discovery Agent or Discovery Consumer, with a slight preference for the latter since Discovery Agent can be thought of as the service running in the Thing for the introduction mechanisms. The word Discoverer is also not easy to pronounce (or not pleasing to pronounce), but that might be related to English not being my mother tongue.

[mlagally]

This is a good proposal that relates to #673

[mmccool]

I would prefer if the definition of "Discoverer" covered only a client searching for TDs and not registering TDs (although technically both actions use different parts of the same API in TDDs). I have added two definitions, as follows, in the PR I will shortly commit:

• Discoverer: An entity which acts as a client of a WoT Discovery service to discover and fetch a Thing Description, e.g. by being introduced to and searching a Thing Description Directory exploration service or fetching a Thing Description directly from the well-known endpoint on a Thing.
• Registrant: An entity which registers a Thing Description with a Thing Description Directory. This entity may or may not be the Thing that the Thing Description describes.

I moved the "e.g." in the definition of "Discoverer" AFTER the "discover and fetch a Thing Description" since that is the definition, not an example; being introduced to and fetching a TD from a Directory is one way to do this, so those are examples.

We don't currently use the term "Registrant" in the WoT Discovery document but I'm going to work on that next, addressing this and several other issues that Ben noted recently in wot-discovery issue #299

[mmccool]

BTW note both "discoverer" and "registrant" are actual English words with definitions aligned with these definitions:

• Discoverer: the first person to find or explore a place; the first person to find or observe a substance or scientific phenomenon.
• Registrant: a person who registers something.

[benfrancis]

TIL that "discoverer" is a word. English is weird 😆