Wot-thing-description: Rename of label to title and enum titles 'oneOf'

[benfrancis]

When adding labels to properties and actions in Mozilla's implementation as per the latest Editor's Draft, @mrstegeman asked:

Should there also be labels for events, event data and action inputs?

As an example use case, we generate graphical forms for action inputs from the JSON Schema in a Thing Description.

For example, an action like:

{
  "actions": {
    "advanced": {
      "input": {
        "type": "object",
        "properties": {
          "numberInput": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "unit": "percent"
          },
          "integerInput": {
            "type": "integer",
            "unit": "meters"
          },
          "stringInput": {
            "type": "string"
          },
          "booleanInput": {
            "type": "boolean"
          }
        }
      }
    }
  }
}

Would be rendered like this:

It would be nice to provide more human-friendly labels for those input fields.

We also render a log of events, like this:

It could be straightforward to add label to events as well as properties and actions. Could JSON Schema also accommodate human-friendly labels for sub-properties of objects?

[sebastiankb]

Good question. In general, JSON Schema offers the term _title_ for such kind of purpose (also see http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1).

It seems that we have a conflict with TD's _label_ term (which I would prefer). In tomorrow's web meeting I will discuss this issue.

[takuki]

In Hypertext Links in HTML, it is advised that "title" was meant for an advisory title for the linked resource, whereas "label" was a label for the link.

[mkovatsc]

This is related to the label vs name discussion and brings title to the options.

Way forward

• Keep label for rdfs:label usage to label the Linked Data nodes
• Use either name or title to provide UI strings for Interactions as well
• Ask @handrews about the history of title in JSON Schema and how fixed it is

[mkovatsc]

After some distance, I am in preference of title now:

• compatible with JSON Schema
• semantically different from a name -> title is just for UI

[mkovatsc]

@handrews As I saw some recent activity, may I ask your input on the naming of a human-readable field to shortly describe Interactions? (name, label, title, ...)

In particular, I would like to know the history on why 'title' in JSON Schema. My guess is Web Linking, yet (also historically there) a title is for a document and not individual items within a representation...

[handrews]

@mkovatsc There are two title fields: The schema annotation keyword, and the LDO (Link Description Object) keyword. Both predate me. The one in the LDO corresponds directly to RFC 5988/8288's "title" parameter for the HTTP Link header. The schema annotation keyword is unrelated to web linking.

Both are intended for short human-readable descriptions (with description available in both places for longer details). I tend to think of title in the LDO as the human-readable equivalent of rel.

As for title as a schema annotation, like all annotations it is up to a particular application to decide what to do with them. They can be used as form field labels, and I think that usage is common, but they're not specifically intended for that use. There are several JSON Schema vocabularies for form generation- I'm not sure if they use title or have a separate field.

[benfrancis]

@mkovatsc wrote:

A title is for a document and not individual items within a representation

I think that's correct, title in web linking provides a title for the linked document.

From a purely linguistic point of view I'd say that in English "title" is most commonly used to mean the name of a book, document. composition or artistic work. Also the name of a position or job, and in law a "title" is a right or claim to the ownership of property. "name" or "label" seem like more obvious choices for this use case.

@handrews: The only mention of "title" I could find in JSON Schema Core spec is in section 4.3.3. Root Schema and Subschemas. Is that intended as a title for the schema?

[handrews]

@benfrancis The Core spec only defines a few keywords (although in the next draft a few more move over to core for reasons too involved to go into here and not immediately relevant). This means that when we need examples in the Core spec we often have to use keywords from elsewhere. It's on my TODO list to be more clear about where those examples come from.

The two places title is defined are in in the Validation spec as part of the basic schema annotations, and in Hyper-Schema as a link target attribute. The example in Core is using the title from Validation.

[handrews]

Oops forgot to actually answer the question- that title in the root schema is usually considered to be the title of the whole schema document, but as noted where they are defined in the Validation spec, the exact usage of schema annotations is application-defined.

[mkovatsc]

I took the information from http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1

10.1. "title" and "description"

The value of both of these keywords MUST be a string.

Both of these keywords can be used to decorate a user interface with information about the data produced by this user interface. A title will preferably be short, whereas a description will provide explanation about the purpose of the instance described by this schema.

For TD, it is kind of a dice roll between title and name. title does not really fit semantically, but it would be compatible with the above, i.e., Property Interactions and sub-properties from the schema work the same way. If this title is not as settled in JSON Schema -- @handrews comments sound like this ("application-defined") -- name would be better.

May I ask for opinions on which to choose?

[handrews]

@mkovatsc The "can be used to decorate a user interface..." is basically an example of usage (hence "can" rather than "SHOULD" or even "MAY").

"application-defined" in this sense could include the TD saying "in the context of the TD, JSON Schema's title MUST be used as...". Similarly, OpenAPI puts more constraints on the meaning of readOnly and writeOnly (which are also annotation keywords) than JSON Schema proper and JSON Hyper-Schema do.

I wouldn't call the behavior "unsettled". Rather, as we realized the very wide range of possible reasonable uses of these keywords, we settled on deferring specifics to applications to avoid either invalidating common use cases or having an explosion of keywords with very minor behavioral differences among them.

I'm still working on how to best explain this flexibility in the spec.

From a JSON Schema perspective, if title is not ideal and you wanted to add name as an extension keyword within the schema so that it matches name for interactions, that would also be valid. And in draft-08, it will be possible to indicate things like "I'm using the standard draft-08 validation plus a name extension keyword".

[mkovatsc]

@handrews To paraphrase it a bit, I would say the spec encourages to use term title for a string to shown in a UI. Of course applications MAY use it for something differing within their scope or use a different term, but I guess the expectation is that there will be some kind of convergence to increase compatibility with different UIs.

Would you agree with this statement?

[handrews]

@mkovatsc The current spec does give that impression, but I've actually been meaning to take out the UI usage references and emphasize the flexibility instead. The keywords in the Schema Annotation section, including title, all have different use cases depending on how you're using JSON Schema. If you are using it to generate a form UI, then yes, title makes sense to use in the UI. But if you're using it in API documentation, then displaying it as "brief description" or "summary" might make more sense than "title". Some of the other annotation keywords like default are even more complicated in terms of usage.

The larger plan is to have a UI-specific vocabulary, which would build on what's already in the validation spec but would add keywords with clear and predictable UI-oriented semantics. There are similar plans for a code generation vocabulary, which would add keywords to disambiguate things like "is this allOf representing inheritance, or is it just a mechanism to glue multiple field sets together within a single class?"

The current "Schema Annotations" section will still exist as a really basic and flexible set of common keywords, but for more complex scenarios where clear, well-defined semantics are needed, we want to encourage developing specific vocabularies for those scenarios. Most of the work in draft-08 is going towards enabling well-defined, compose-able schema vocabularies. Which is not a real formal concept in JSON Schema right now.

[benfrancis]

Another related use case that has come up is providing human-readable labels for enums.

Where the options for a property or action input are rendered as a drop-down in a form it can be helpful to provide human-readable labels in addition to machine-readable values.

An example pointed to by @trentrand shows two ways this is sometimes done with JSON Schema.

One using a non-standard enumNames field:

{
  type: "number",
  enum: [1, 2, 3],
  enumNames: ["one", "two", "three"]
}

And one using a more standard (from JSON Schema Validation) but verbose schema:

{
  "type": "number",
  "anyOf": [
    {
      "type": "number",
      "title": "one",
      "enum": [
        1
      ]
    },
    {
      "type": "number",
      "title": "two",
      "enum": [
        2
      ]
    },
    {
      "type": "number",
      "title": "three",
      "enum": [
        3
      ]
    }
  ]
}

Either of which might be rendered as:

<select>
  <option value="1">one</option>
  <option value="2">two</option>
  <option value="3">three</option>
</select>

[mkovatsc]

@sebastiankb We need to move forward here. Since there were no objections, I would say we change InteractionPattern to have the field/member title for a short human-readable text for UIs and also add title to DataSchema -- similar to description for a longer human-readable text.

Choosing title fits with Web Linking terminology, the JSON terminology, where "name" is the identifier, and also with RDF, where "label" is for describing the underneath ontology. It also fits JSON Schema, as they have an existing "multi-prupose term" title, which we refine for the UI use case.

@benfrancis The issue with enum titles should probably brought to JSON Schema, and we pull it back into TD. @handrews , of course we can work together on this.

[mkovatsc]

@benfrancis BTW, from where do you get the vocabulary for unit? While it would be nice to have unit in the TD core vocab, there are so many definitions/vocabularies to pick from, so that importing a specific context for units appears better at the moment. If there would be a dominant unit vocabulary, we could include this in the core... @vcharpenay, options?

[benfrancis]

@mkovatsc wrote:

Choosing title fits with Web Linking terminology, the JSON terminology, where "name" is the identifier, and also with RDF, where "label" is for describing the underneath ontology. It also fits JSON Schema, as they have an existing "multi-prupose term" title, which we refine for the UI use case.

This rationale all makes sense, it's just slightly unfortunate that we landed on "title" because linguistically "title" feels a bit awkward for these use cases, both "name" and "label" would sound better to my ear. I don't have another suggestion so I've asked our team for input just in case.

BTW, from where do you get the vocabulary for unit?

We reference SI units (The [SI] reference in ReSpec points to https://www.bipm.org/en/publications/si-brochure/) and use the long form (e.g. "metre"/"kilogram").

[handrews]

@mkovatsc the recommended way for to handle titled enumerations of uniform type is:

{
  "type": "number",
  "oneOf": [
    {"const": 1, "title" "one"},
    {"const": 2, "title": "two"},
    {"const": 3, "title": "three"}
  ]
}

One-element enums are kind of weird, but const makes the intent perfectly clear and de-clutters the punctuation.

[mkovatsc]

@handrews Thanks, that should solve the use case.

@benfrancis I fail to get a proper vocabulary from https://www.bipm.org/en/publications/si-brochure/. It seems to be just a documentation about the SI system. For instance, there is already a mismatch between their "metre" and your "meters" used above. This will not work for M2M.

[benfrancis]

@mkovatsc wrote:

I fail to get a proper vocabulary from https://www.bipm.org/en/publications/si-brochure/. It seems to be just a documentation about the SI system.

If by a "proper vocabulary" you mean an RDF vocabulary, then no, we haven't found that necessary. It's a human readable specification. The 7 base units are:

• metre
• kilogram
• second
• ampere
• kelvin
• mole
• candela

then there are many possible derived units and non-SI units accepted for use with the SI.

For instance, there is already a mismatch between their "metre" and your "meters" used above.

That's just a mistake on my part.

[takuki]

For ontology for units, I hear QUDT more often. SSN, for instance, makes an informal references to QUDT and OM.

[draggett]

I chatted with the people behind QUDT and their work is pretty thorough, and relates to the underlying dimensional basis for each unit. However, QUDT can be rather cumbersome compared to a simpler approach that defines vocabularies of terms that combine what is being measured (e.g. electrical current), the unit (amperes) and the scale (1000 for milliamperes). An ontology then maps these to the QUDT framework. In practice, for JSON, you can then write "units": "milliamps".

The common abbreviations for units in a few cases may be used for different things in different fields. This can be easily addressed through the JSON-LD context for a given field. People would then be able to write "units": "mA". Common abbreviations may use greek letters e.g "μA" for microamps. These can be a little difficult to enter, but browser extensions etc. make this much easier.

[lgleim]

I would also like to throw the UCUM specification into the ring. There is a recent paper by @maximelefrancois86 (one of the SSN editors) which introduces a very usable unit system.

[mkovatsc]

@lgleim Yes, I also had that one in mind, as it was used in CoRE, LWM2M, and IPSO before. I was not sure if an RDF vocabulary exists ready to use.

[lgleim]

@mkovatsc The corresponding vocabulary would be http://w3id.org/lindt/custom_datatypes - as far as I understand there are two ways this vocabulary could be employed:

1. using the http://w3id.org/lindt/custom_datatypes#ucum datatype, which "Maps lexical forms with a UCUM unit to their corresponding measures according to the International Systems of Quantities."
2. using any of the other concrete unit types defined in the vocabulary directly

There is also a nice playground to see the vocabulary in action: https://ci.mines-stetienne.fr/lindt/playground.html

I have seen a demo of UCUM + RDF before and found it quite convincing but I am not familiar with QUDT. Maybe @maximelefrancois86 can clarify a bit more, since he should be familiar with both vocabularies given his involvement in the SSN design?

[sebastiankb]

fyi: title is now compiled in the latest TD version for Lyon: https://htmlpreview.github.io/?https://github.com/w3c/wot-thing-description/blob/td4lyon/index.html

[sebastiankb]

oneOf is now also part in the TD: https://github.com/w3c/wot-thing-description/commit/094e9aec4c7fe94ca93e94e3dbdc47d1a113159d

[takuki]

oneOf is now also part in the TD: 094e9ae

@sebastiankb ,thank you for the change.
Now with "oneOf", we are able to describe titles for enumerated items.

[sebastiankb]

@takuki thanks