Representing ImageObject in event structured data for live performances

[dlh28]

Following a discussion over email regarding prototyping activities with Evenko and La Vitrine, @fjjulien, @saumier, and @christianroy agreed upon a set of best practices for representing an ImageObject nested entity in Event structured data:

Minimum required property:

• url

Additional recommended properties:

• copyrightNotice (with attribution to the copyright owner)
• usageInfo (with a link to suggested guidelines for reusing event images)
• author (using a regex to extract the credit name from any caption at the source)
• disambiguatingDescription (with a formulaic description, such as "Image of [event name], sourced from [website domain name]"
• creditText (to credit all parties, including the photographer, production company and performers depicted onstage)
• caption (formulaic caption)
• description (containing alt text, if available)

Code:

"image":
{
  "@type": "ImageObject",
  "url": "--URL officiel de l'image : Official image URL--",
  "copyrightNotice": "--licence et attribution au propriétaire du droit d'auteur : license and attribution to the copyright owner--",
  "usageInfo": "--lien vers les directives concernant la réutilisation des images d'événements : link to suggested guidelines for reusing event images--",
  "author": {
       "@type": "Person",
      "name": "--Nom du photographe ou créateur d'image : Name of photographer or image creator--"
                     },
  "disambiguatingDescription": "--description sous forme de formule, telle que « Image de NOM DE L'ÉVÉNEMENT, provenant de NOM DE DOMAINE DU SITE WEB » : formulaic description, such as 'Image of EVENT NAME, sourced from WEBSITE DOMAIN NAME'--",
  "creditText": "--credit photo complet, y compris le nom du photographe, de la compagnie de production et des interprètes représentés sur la scène : full photo credit, including the name of the photographer, production company and performers represented onstage --",
  "caption": "--explication d'une ligne de ce que l'image représente : one-line explanation of what the image represents--",
  "description": "--Alt texte, si disponible : Alt text, if available--"
},

Modelling rationale:

• Although contentUrl is the more common Schema property used to link to the image address, Gregory Saumier-Finch advocated for url to be used instead, because "the property is already commonly used for other classes".
• description was chosen instead of caption as the preferred Schema property to describe alt text, because caption "is clearly intended to supply another type of content" (Frédéric Julien, translated).
• Frédéric Julien argued that even in the absence of a description, disambiguatingDescription is an extremely useful property to include in imageObject structured data, because it "[encodes] certain information in the image object that is specific to the official Event entity to which the image relates, so that this information remains accessible even when the image is reused in a calendar that consumes data from Artsdata" (translated). He continued, "I would have liked to do this with a property whose value would be a URL, but I haven't found any property that would be semantically correct. schema:About might be a candidate, but it seems to me that the target should be the performance work rather than the [on-stage] representation [of the work]" (translated).

Usage notes:

• If a nested ImageObject is available at a source, the script should prioritize attribute-value pairs at the source, and then enrich them.
• When converting an image URL to an imageObject, regex may be used to extract the author value from the credit name from any caption at the source.

For more information about the most commonly used image properties in Artsdata, consult this SPARQL.

edited Dec 3, following feedback from the Artsdata Community Group

[fjjulien]

The property name could also be used to convey the image title. This value could be pushed into an html image title attribute. Very few sources bother documenting their image title, but I nonetheless wanted to record this mapping in this discussion thread:
"schema:name" = "hmtl:title"

[dlh28]

I don't understand what you mean by "html image title attribute". Are you referring to the title given to the image (ex: Event Name), the title with the file type suffix (ex: Event Name.jpeg) or the full image address (ex: https://sitename.com/event_name.jpeg)?

[fjjulien]

@dlh28 title is an attribute that can be used with any html element. It's most commonly used on web pages themselves, but it can also be used within img elements. For example, if the image is representing a chart, you could use it to give the chart a name. If the image is representing a show, you could use it to name the image by the name of the show.

An image's title is independent from the file name. They can sometimes be almost the same, but can at other times differ significantly. The title value is usually only visible to a human when you mouse over the image: the title will then pop up next to the mouse icon.

As I wrote above, it is too seldom used with images, so there's no need to make mention of it in the main model for image objects.

[saumier]

Footlight CMS is adding "creditText" and "caption" to the current "ImageObject". Is there any feedback from the group about this JSON-LD for images?

CMS ImageObject:

"image":
{
  "@type": "ImageObject",
  "url": "image url",
  "description": "Alt text if available",
  "creditText": "optional photo credit entered into CMS",
  "caption": "optional one-line caption to be displayed on the webpage to accompany the image. Not the same as 'description'.",
  "thumbnailUrl": "thumbnail image url",
  "width":"width of the full image represented by 'url' (not 'thumbnailUrl')",
  "height":"height of the full image represented by 'url' (not 'thumbnailUrl')"
}

[christianroy]

LGTM!

[fjjulien]

@saumier For display purposes, I would like to signal that the creditText, if provided, should always be included within an image's caption, even when no content is provided under the caption property.

In other words, a displayed image's caption should follow this kind of format:
<caption content><" " (a space, unless caption content is absent)><creditText content>

Rationale:
This is a legal and moral obligation.

[fjjulien]

@saumier In addition, as suggested above, I recommend integrating a disambiguatingDescription following this kind of formula:
"Image of <name of the main entity in which the ImageObject is nested>, sourced from <website domain name from the url of the main entity in which the ImageObject is nested>."

Rationale:

• In the absence of a caption and/or a creditText, Artsdata should strive to provide minimal information identifying the source of the image.
• For display purposes, the disambiguatingDescription could be displayed 'as is' in the absence of a caption and a creditText.

[fjjulien]

@saumier I have been developing an Artsdata Image Policy, which could be referenced under usageInfo. We could pass on the policy as a straight URL or else describe it as a nested CreativeWork object.

I published the draft version of the Image Policy (en français) in GitHub at: https://github.com/culturecreates/artsdata-data-model/blob/master/doc/fr/image_policy.html.md An English translation should be available soon.

I'm not sure if you will want to include this in the Footlight CMS ImageObject modelling, but it should definitely be included in the ImageObjects for the Artsdata Planet evenko project.

[saumier]

@saumier For display purposes, I would like to signal that the creditText, if provided, should always be included within an image's caption, even when no content is provided under the caption property.

In other words, a displayed image's caption should follow this kind of format:

<" " (a space, unless caption content is absent)>

@fjjulien This makes perfect sense, only that it is up to the implementor of the website. Footlight CMS cannot enforce this.

@saumier In addition, as suggested above, I recommend integrating a disambiguatingDescription following this kind of formula:
"Image of <name of the main entity in which the ImageObject is nested>, sourced from <website domain name from the url of the main entity in which the ImageObject is nested>."

@fjjulien Sounds like a good suggestion. We will add this to the Evenko project.

@saumier I have been developing an Artsdata Image Policy, which could be referenced under usageInfo. We could pass on the policy as a straight URL or else describe it as a nested CreativeWork object.

I published the draft version of the Image Policy (en français) in GitHub at: https://github.com/culturecreates/artsdata-data-model/blob/master/doc/fr/image_policy.html.md An English translation should be available soon.

@fjjulien Ok. We will include this in the Evenko project.

[fjjulien]

@saumier I'm not sure if I created the image policy file in the right location. I note that you didn't use a doc/language path for documentation in the Artsdata data model repository. If it is not in the right place, please move it and create a placeholder document for the English version.

[saumier]

@fjjulien I was just looking into this.

In this case, although we have documentation in the data-model repo, I prefer to put it in nebula repo. I have placed it there for now and if you agree then we can finalize it. The reason is that it creates a more official and authoritative url:
https://kg.artsdata.ca/doc/image_policy
versus
https://github.com/culturecreates/artsdata-data-model/blob/master/doc/fr/image_policy.html.md

Also, https://kg.artsdata.ca/doc/image_policy can redirect to either language https://kg.artsdata.ca/fr/doc/image_policy or https://kg.artsdata.ca/en/doc/image_policy and in the future there is room to detect "fr" language in the user's preferences.

I will add an auto-deploy script in the nebula repo like in the data-model repo so changes you make will become visible in the browser automatically.

We can sit down in February to adjust the look and feel of the Markdown on Nebula if you would like to make it look more like the one on the data-model repo. The documents will not change, only the css for the markdown. That is one advantage of markdown :-) as well as making the documents easier to edit by a human.

[fjjulien]

@saumier Publishing the policy in the Nebula repository makes total sense. Merci!