[question] Why is title or description necessary when titles or descriptions are present?

[egekorkan]

Coming from https://github.com/thingweb/thingweb-playground/issues/149

The TD spec has the following assertion:

When title and titles or description and descriptions are present in a TD document, each title and description member SHOULD have a corresponding titles and descriptions member, respectively.

This means that the following TD snippet is not valid since the values found in the title and description are not present in titles and descriptions respectively.

{
   "@context": "https://www.w3.org/2019/wot/td/v1",
   "titles":{
      "de":"Deutscher Titel"
   },
   "title":"English title",
   "descriptions":{
      "de":"Deutsche Beschreibung"
   },
   "description":"English description"
}

As @citrullin mentioned in the above-linked issue, this results in larger TDs where the benefit is not at all clear. Why is this assertion needed? If there is a specific reason, I think it should be explained near the assertion.

[danielpeintner]

The only argument/benefit of having it as it is now is that one can figure our the language of the current title or description.

With the sample above there is no way to detect that "title":"English title" is actually English while IF we have

   "titles":{
      "de":"Deutscher Titel",
      "en":"English title"
   },
   "title":"English title"

it is possible to find out the current language....

Note: the argument about increased document size is a good argument. Having said that, IF one wants to tackle this an optimized format like deflate or others (e.g., EXI, EXI4JSON. I think CBOR not) would most likely vanish the second appearance .

[danielpeintner]

Note: It seems JSON-LD does this differently (there is no plural form).

see https://json-ld.org/spec/latest/json-ld/#language-indexing A term can be a string or a map of strings with language identifiers.

[egekorkan]

I have also forgotten to include that there should be an @language tag in the @context field. For the example above, there would be the following:

{
    "@context": [
        "https://www.w3.org/2019/wot/td/v1",
        { "@language" : "en" }
    ],
//...
}

[sebastiankb]

I think the spec is quite clear that the title is NOT mandatory if titles is used (same for description).

TD instances may also combine the use of title and description with titles and descriptions. When title and titles or description and descriptions are present within the same JSON object, the values of title and description MAY be seen as the default text.

[Citrullin]

I think the spec is quite clear that the title is NOT mandatory if titles is used (same for description).

TD instances may also combine the use of title and description with titles and descriptions. When title and titles or description and descriptions are present within the same JSON object, the values of title and description MAY be seen as the default text.

True, thanks.

{
    "@context": [
        "https://www.w3.org/2019/wot/td/v1",
        { "@language" : "en" }
    ],
    "titles":{
      "de":"Deutscher Titel",
      "en": "English title"
   },
   "descriptions":{
      "de":"Deutsche Beschreibung",
      "en": "English description"
   },
//...
}

should be fine then.

The confusion came, from my side, from the overview. The quoted text maybe a bit confusing, since it only mentions "MAY be seen as the default text.". But it doesn't say that title and description can be skipped. Thanks for the clarification.

[sebastiankb]

should be fine then.

almost. Independent of language consideration, title is always mandatory at the top level.

Indeed, we should be clearer about this kind of exception in the TD specification. Thanks for the hint.

[Citrullin]

should be fine then.

almost. Independent of language consideration, title is always mandatory at the top level.

Indeed, we should be clearer about this kind of exception in the TD specification. Thanks for the hint.

That was part of the discussion. If you have the language tag and titles, why do you need additionally to repeat these information in title? Or the other way: Why does this language tag has to be present in titles, when it is already given in title?

[sebastiankb]

In the early version of the TD the title was name and was always mandatory from the beginning. This kind of information is a kind of human-readable identifier for the Things. However, after the W3C's review of internationalization, the term name was criticized for lacking association with a language. That's the reason why it was renamed to title where we have the throughout titles concept.

I fully agree, in this case it is a kind of redundancy information. However, title at the top level is really the exception. Changing this to optional would lead to backwards compatibility problems.

Regarding compactness, maybe the language negotiation mechanism can be also an option:

Another possibility to set the default language is through a language negotiation mechanism, such as the Accept-Language header field of HTTP. In cases where the default language has been negotiated, an @language member MUST be present to indicate the result of the negotiation and the corresponding default language of the returned content. When the default language has been negotiated successfully, TD documents SHOULD include the appropriate matching values for the members title and description in preference to MultiLanguage objects in titles and descriptions members. Note however that Things MAY choose to not support such dynamically-generated TDs nor to support language negotiation (e.g., because of resource constraints).

[danielpeintner]

I know I mentioned it already and it would be a breaking change but JSON-LD does use it differently (see see https://json-ld.org/spec/latest/json-ld/#language-indexing)

"label": "Just a simple ..."

vs.

  "label": {
    "en": "The Queen",
    "de": [ "Die Königin", "Ihre Majestät" ]
  }

[sebastiankb]

@danielpeintner this approach is not aligned with JSON Schema, since there is no "title" : {...}

[danielpeintner]

@danielpeintner this approach is not aligned with JSON Schema, since there is no "title" : {...}

I see there is no one-fits-all solution: either JSON-LD or JSON Schema. Note: There used to be a related issue, see https://github.com/json-schema-org/json-schema-spec/issues/53

[egekorkan]

@danielpeintner this approach is not aligned with JSON Schema, since there is no "title" : {...}

I don't understand the relation of this to JSON Schema ?

[sebastiankb]

The title and description keywords must be strings.

https://json-schema.org/understanding-json-schema/reference/generic.html#id2

[egekorkan]

I see, I never related them to JSON Schema since on the Thing and Interaction level (except Properties), they are not about DataSchemas.

[sebastiankb]

title (and description) are not limited to the top level in JSON Schema and can be used on data model level as well. Therefore they are definitely part of the data schema definitions in the TD.

JSON Schema includes a few keywords, title, description, default, examples that aren’t strictly used for validation, but are used to describe parts of a schema. None of these “annotation” keywords are required, but they are encouraged for good practice, and can make your schema “self-documenting”.

[egekorkan]

Indeed, we should be clearer about this kind of exception in the TD specification. Thanks for the hint.

This is not fixed yet but there is a propose closing label. Also the first comment of the issue is not resolved in my opinion.

[sebastiankb]

I think the question is clearly answered with a way of a workaround. However, you are right the label should be "PR needed" for the clarification of title usage at top level.

[egekorkan]

I think that the above linked workaround does not solve the following:

Why does this language tag has to be present in titles, when it is already given in title?

So title on the top level is one thing to fix, this is another thing to clarify.

[egekorkan]

Just to be clear, what is exactly needed to fix this? Is the following proposal for a paragraph in section 6.3.2 ok?

The title term in the Thing level provides a way to identify and name a Thing. Thus, it is mandatory even when the titles member is present. However, the title in other levels is optional when an @language tag is provided in the @context which can be used to identify the language. If @language is not present in the @context, title should be provided in order to provide the default language.

In the end, I don't think that we have a resolution for the root of the problem, i.e. the following assertion:

When title and titles or description and descriptions are present in a TD document, each title and description member SHOULD have a corresponding titles and descriptions member, respectively.

[benfrancis]

Proposal: For TD 2.0 merge title and titles into a single title member which can either be a string or an array.

That doesn't solve the problem in 1.1, but would remove a lot of redundancy and would be more consistent with @type, unit, oneOf, allOf, scopes, contentType and contentCoding all of which can be be a string or an array. It's just not backwards compatible and may not be valid JSON Schema, but maybe that's OK?

[sebastiankb]

I would +1 to move this topic to TD 2.0. My impression is that we have to change some assertions that may break backwards compatibility. @Citrullin would be this ok for you?

@benfrancis

Proposal: For TD 2.0 merge title and titles into a single title member which can either be a string or an array.

The problem with this approach would be that title is coming from JSON Schema and does not allow being typed as array (or map).

[benfrancis]

The problem with this approach would be that title is coming from JSON Schema and does not allow being typed as array (or map).

I understand. Given that the specification already only re-uses a subset of features from JSON Schema, is there a reason that the parts that are used need to be strictly compliant with the JSON Schema specification (e.g. to be able to use certain tooling)?

[benfrancis]

is there a reason that the parts that are used need to be strictly compliant with the JSON Schema specification

Related: #1101

[sebastiankb]

I understand. Given that the specification already only re-uses a subset of features from JSON Schema, is there a reason that the parts that are used need to be strictly compliant with the JSON Schema specification (e.g. to be able to use certain tooling)?

The main goal is simply to reuse existing tools / libs that follow the JSON schema specifications. I think most validator tools check the type of "title", otherwise they throw an error. I did a quick check with this tool here.

[Citrullin]

I would +1 to move this topic to TD 2.0. My impression is that we have to change some assertions that may break backwards compatibility. @Citrullin would be this ok for you?

@benfrancis

Proposal: For TD 2.0 merge title and titles into a single title member which can either be a string or an array.

The problem with this approach would be that title is coming from JSON Schema and does not allow being typed as array (or map).

No problem, I already deal with it in my code. It's could be more elegant, but it is fine. I rather prefer though to be a fixed type. It removes annoying code from my side. Moving it to 2.0 sounds good to me.