Description should be short abstract of resource

[azaroth42]

Original: We don't really need description as there's no limit on the number of characters that can go into a metadata value. It would also allow for setting the label to something else, and for it to be appropriately internationalized. At the moment it's impossible to override the client provided label. The use case for keeping description separate is if it should be presented in a different discursive block of text, compared to the more fielded values in metadata. This could be a flag on the metadata "pair" instead?

2017-09-29: See #1242 (comment) for updated issue

[workergnome]

Or as a convention in the UI, not in the spec. Otherwise, we're drifting into semantics in the metadata, which I'm firmly against.

[jronallo]

Mainly 👍 on this.

Are there discovery use cases where it is useful to have a separate description? So similar to the way that the major search engines use the meta description in the search result snippet having a description available for that kind of use could be nice. If that were through a flag on the metadata pair that would be fine.

[azaroth42]

Or ... a texts (or similar) property that can have a label and value, but the value is longer. Then there could be a "description" text, a "bibliography" text, a "history" text and so on. Still nothing semantic, and removes the current semantics of description in favor of just distinguishing long form blocks of content from tombstone metadata.

[workergnome]

I don't see any real point in texts: if a client wants to treat long metadata values differently than short ones, it's easy to detect and treat differently. Otherwise, you're going to have to define what "long" means.

[azaroth42]

Eds' Proposal: Description should be an abstract or summary of the resource only, and not displayed at the same time as the metadata properties. Thus the display algorithm would be label AND (description OR metadata)

Splitting the clarification of metadata to a separate issue.

[azaroth42]

Alternate proposal for consideration: Deprecate description in favor of a textual thumbnail

[mikeapp]

My earlier suggestion was that the new description shouldn't be displayed with metadata, since it may be redundant (we suggest duplication of selected metadata as a common use case in the current description). This wouldn't be true of a thumbnail image.

[workergnome]

@mikeapp No? In a different context, perhaps, but you would never show the thumbnail and the image in the same place in the same context. (I'm assuming that a image selector at the bottom, or the navigation pane on the left, of whatever sort of UI convention we're talking about is a different context, where it would be appropriate to either show the description or the thumbnail.)

[azaroth42]

This is done according to the issue: http://prezi3.iiif.io/api/presentation/3.0/#description

But noting the Textual thumbnail alternative. Perhaps we should split that out to a separate issue? Otherwise, how to decide?

[azaroth42]

Re:

Are there discovery use cases where it is useful to have a separate description?

The current description text would live with other long texts, which at the moment would be in the metadata block, allowing it to have a label as well as a value. As far as discovery goes, any semantic description would be in a referenced seeAlso.

[azaroth42]

To argue against a textual thumbnail: Currently thumbnails are external resources, and the property could be documented in the linking section rather than technical. They are dereferenced and pulled in to be rendered by the browser. For language-bearing content, they require the newly added language property. Conversely, all textual content is provided inline using the language map construct.

If description was a textual thumbnail, we would have added an exception where the text content is reified into a resource instead of being the value of a property. The value of the thumbnail would not be a language map, but instead a raw string following the TextualBody pattern in Annotations.

{
  "metadata": [
    {"label": [{"en": "Summary"}], "value": [{"en": "Summary here"}]}
  ],
  "thumbnail": [
    {"type": "Text", "value": "Summary here", "language": "en"}
  ]
}

I think this is more confusing than retaining a property, though renaming from description would prevent cross-version headaches. A v2 to v3 transformer would need to move v2 description into the metadata list, as the usage has changed in a significant way.

Proposal: Rename description to summary with a value of a language map, and the usage described above.

[tomcrane]

Referencing #1288 (comment), description as alt text.

[workergnome]

I like the idea of a summary property, particularly with the #1288 motivation included. Captures the same intent as an altText, in that it's designed to be a substitute for the visual representation, not an addendum to it.

[zimeon]

👍 to summary with a value of a language map

[mikeapp]

Also 👍

[azaroth42]

Discussion on 11/22 Call: Approved

[glenrobson]

Just thinking how this would work with a non English language manifest. Would it look like:

"metadata": [
    {"label": [{"cy-GB": "Crynodeb"}], "value": [{"cy-GB": "Welsh Summary here"}]}
  ],

and if so how would a client be able to treat this differently to any other metadata field? Particularly if its used as an altText?

[azaroth42]

Your example is correct. It would treat it like other metadata fields, but need additional logic if "Welsh Summary here" is long. It wouldn't be used for the alt text ... that might be summary, but the discussion for that issue (#1288) was that we don't really know what we're doing or where to manage that content yet. If it's necessary to be different from summary then it would be a new property, not in metadata.

[glenrobson]

Sorry I'm still a little confused.

So is it a question of whether you get rid of an identifiable description/summary field? or is it that you will have a field named summary in the metadata section? If its the latter what was the reason for moving it inside the metatadata section?

[mikeapp]

The suggestion here is to remove the description property and introduce summary.

Long-form prose descriptions can comfortably be published in metadata, provided clients take into account the possibility that large amounts text may need to be presented to the user (this is #1270). So the utility of the description as a standalone property is limited.

The new summary property will contain a short description or summary of the object that will not be shown when metadata is being displayed. The summary can thus repeat content from metadata (or be wholly included in metadata) without causing the display of redundant text to the user.

[azaroth42]

Closed by #1326