Offer Modelling

[saumier]

How should Artsdata model Offers in RDF? The solutions should cover the most common use cases for events in the cultural sector, and be sufficient to drive a website page with ticketing information displayed and buttons with links to buy tickets or register.

Common use cases:

1. Offer for a paid event with buy url
2. Offer for a free event
3. Offer for a free event that requires registration
4. Offer for a paid event that requires registration
5. Offers with multiple prices
6. Offer for a paid event without a price (price is not known)
7. Offer for a paid event without a buy url (pay at the door)

See discussion culturecreates/artsdata-planet-lavitrine#3

See issue #80

[saumier]

Here is an attempt at answering the Offer modelling question. I have drawn from all the lengthy discussions culturecreates/artsdata-planet-lavitrine#3 as well as issue #80. Most of the user cases are covered. I'll add the remaining use cases in a second pass.

Examples

Offer for a paid ticket with buy url.

 "offers": {
    "@type": "Offer",
    "price": "13.00",
    "url": "http://www.ticketfly.com/purchase/309433"
  }

Offer for a free event with more info url.

 "offers": {
    "@type": "Offer",
    "price": "0",
    "url": "http://event.info"
  }

Offer for a free event that requires registration. Registration ends on a date before the event.

 "offers": {
    "@type": "Offer",
    "price": "0",
    "additionalType": "http://kg.artsdata.ca/resource/RequiresRegistration" ,
    "url": "http://register.here.com",
    "validThrough": "2023-11-01T00:00:00Z"
  }

Offer for a paid event that requires registration.

 "offers": {
    "@type": "Offer",
    "availability": "http://schema.org/InStock" ,
    "price": "20",
    "additionalType": "http://kg.artsdata.ca/resource/RequiresRegistration" ,
    "url": "http://register.here.com"
  }

Offer with 2 prices and different dates when tickets can be bought, and a common buy url and ticketing info.

 "offers":  [ 
  {
    "@type": "Offer",
    "availability": "http://schema.org/InStock" ,
    "name":"Regular"@en,
    "price": "20.50,
   "validFrom":"2023-11-00T00:00:00Z"
  },
 {
    "@type": "Offer",
    "availability": "http://schema.org/InStock" ,
    "name":"Desjardins Earlybird"@en,
    "price": "10.00",
    "validFrom":"2023-10-15T00:00:00Z"
  },
  {
    "@type": "AggregateOffer",
    "url": "http://all.tickets.here",
    "name":"Children under 12 are free. Box office 514-123-4567."@en
  }
]

Formal model expressed using SHACL

Offer Class

:OfferNode 
    sh:targetClass schema:Offer ;
    sh:name "Offer"@en,
            "Offre"@fr ;
    sh:description "An offer to sell tickets to an event. For more info see [Google doc](https://developers.google.com/search/docs/appearance/structured-data/event#structured-data-type-definitions)"@en ;
    sh:property 
                         :availabilityProp ,
                         :urlProp ,
                         :validFromProp ,
                         :validThroughProp ,
                         :priceProp ,
                         :priceCurrencyProp ,
                         :nameProp ,
                         :additionalTypeProp .

Offer Properties

:availabilityProp
    sh:path schema:availability ;
    sh:in  (    schema:InStock
                schema:SoldOut
                schema:PreSale  
                schema:Discontinued  ) .

:urlProp
    sh:path schema:url ;
    sh:name "URL"@en ,
            "URL"@fr ;
    sh:description "URL to the ticket purchase or registration page"@en ;
    sh:minCount 1 ;
    sh:maxCount 1 ;        
    sh:nodeKind sh:IRI .

:validFromProp
    sh:path schema:validFrom ;
    sh:name "Valid From"@en ;
    sh:description "Availability start date and time, in ISO 8601 format "@en ,
                   "Date et heure du début de la disponibilité, au format ISO 8601"@fr ;
    sh:datatype xsd:dateTime .

:validThroughProp
    sh:path schema:validThrough ;
    sh:name "Valid Through"@en ;
    sh:description "Availability end date and time, in ISO 8601 format "@en ,
                   "Date et heure du fin de la disponibilité, au format ISO 8601"@fr ;
    sh:datatype xsd:dateTime .

:priceProp
    sh:path schema:price ;
    sh:name "Price"@en ,
            "Prix"@fr ;
    sh:description "Price in format 9.99. Use 0 for free events."@en ,
                   "Prix au format 9.99. Utilise 0 pour les événements gratuits."@fr .
    sh:maxCount 1 .

:priceCurrencyProp 
    sh:path schema:priceCurrency ;
    sh:name "Currency"@en ,
                    "Devise"@fr ;
    sh:description "Currency is CAD or USD."@en ,
                   "Devise est CAD ou USD."@fr ;
    sh:maxCount 1 ;
    sh:in  ( "CAD" 
             "USD " ) .

:nameProp 
    sh:path schema:name ;
    sh:uniqueLang true .

:additionalTypeProp
    sh:path schema:additionalType ;
    sh:name "Offer type"@en ;
    sh:description "Artsdata controlled vocabulary for offer types."@en ;
    sh:in  (   adr:RequiresRegistration  ) .

[saumier]

@fjjulien @troughc Let me know if you think we are making progress and if you can read the SHACL with the names and descriptions.

[troughc]

@saumier I took a look at the formal model, offer properties, and offer examples above and was able to read everything - very clear, thank you.
I like that I can add the properties I need depending on the requirements of the offer. For example, in "Offer for a paid event that requires registration" it be possible to add the validFrom property if I needed to. Thanks!

[fjjulien]

@saumier Yes, we are definitely making progress. But I think we're still missing nesting for AggregateOffers. I'll provide a full answer and an example below.

[fjjulien]

@saumier I don't think that the AggregateOffer should be at the same level as the individual offers objects. In order for the attribute-value pairs of the AggregateOffer to be inherited to the individual offers, these individual offers must be nested within the AggregateOffer object. The examples provided in the schema documentation for AggregateOffer concur with this view.

If I was following my logic (and the Schema documentation) I would rewrite your example thusly.

Offer with 2 prices and different dates when tickets can be bought, and a common buy url and ticketing info.

"offers":   
  {
    "@type": "AggregateOffer",
    "url": "http://all.tickets.here",
    "name":"Box office 514-123-4567."@en,
    "priceCurrency":"CAD",
    "lowPrice":"0",
    "highPrice":"20.50",
    "offerCount": "3",
    "offers": [
      {
        "@type": "Offer",
        "availability": "http://schema.org/InStock" ,
        "name":"Regular"@en,
        "price": "20.50,
        "validFrom":"2023-11-00T00:00:00Z"
      },
      {
      "@type": "Offer",
        "availability": "http://schema.org/InStock" ,
        "name":"Desjardins Earlybird"@en,
        "price": "10.00",
        "validFrom":"2023-10-15T00:00:00Z"
        "validThrough":"2023-11-00T00:00:00Z"
      },
      {
        "@type": "Offer",
        "name":"Children under 12 are free."@en
        "price": "0",
        "validFrom":"2023-11-00T00:00:00Z"
      }
    ]
  }

[saumier]

I like this. What happens if there is only a simple Offer and no AggregateOffer? If we only show the Offer then this will be inconsistent for developers. If we should an AggregateOffer that only has a nested Offer then this seems unnecessary. Because of this question I flattened the nesting. But removing the nesting is not really any better for developers and loses the semantic clarity of nesting.

Any other feedback?

[fjjulien]

If there is only a single Offer entity, then we should not require the use of the AggregateOffer type (and of any Offer nesting): all attribute-value pairs should be directly linked to this one Offer entity, as you have it for all other use cases. The purpose of the AggregateOffer type is really only to reduce redundancy when there are several Offers and lots of attributes for each one. As a matter of fact, if an event only had two or three offers and not much information associated with each one, they could be described as a direct array without an AggregateOffer grouping. There would be a little redundancy, but it would still be conceptually correct.

If you are concerned about inconsistency for developers (if, for example, a given event with multiple offers was to be described by different sources either with an AggregateOffer or as a straight array of fully developed Offers), then we could keep the modelling simple and choose not to recommend AggregateOffer at this point. AggregateOffer can make the code slightly shorter, but it adds complexity. I would be fine if we left it out.

[saumier]

The Footlight CMS Offer model is evolving based on input from Tout-Culture asking to add email or url to paid and register offers. An email is useful for courses that don't have websites. Example: Janet is giving a pottery course and wants you to email her to RSVP. Isabelle has workshops that are paid, but you need to first email her and she can arrange for payment. See this issue in Footlight CMS culturecreates/footlight-app#950

[saumier]

Proposal to allow a schema:Offer entity to have a property schema:url that is "mailto:[email protected]" instead of an http.

The SHACL can be made to allow both protocols:
sh:nodeKind sh:IRI ; sh:pattern "^http|mailto" ]

[fjjulien]

Est-ce que ça pourrait avoir du sens d'employer AggregateOffer dans les données structurées JSON-LD d'un site web sans que les offres individuelles ne soient détaillées?

Je m'explique.

Geneviève et moi nous sommes réunis hier pour discuter de notre présentation à la Matinée numérique du Forum Avantage Numérique, le 21 mars. Genviève m'y a expliqué que La Vitrine utilisait l'URL de l'entité Offer en guise de point de donnée pour la réconciliation d'événement : si deux événements ont la même URL d'offre et la même URL de lieu, alors il s'agit du même événement. C'est une stratégie de réconciliation qui me semble logique et efficace. Ça pourrait notamment expliquer pourquoi Google accorde tant d'importance aux données structurées d'offre. Si on retient ces deux hypothèses comme logiques et plausibles, alors il est d'autant plus pertinent pour les organismes artistiques de s'assurer d'inclure les métadonnées d'offres dans leurs données structurées schema.
J'y vois aussi un autre scénario d'utilisation très important du point de vue de l'organisateur : une donnée d'offre précise combinée à une donnée organizer précise et vérifiable, peut aider Google à diriger ses usagers vers le site de vente primaire plutôt que vers un revendeur.
Conséquemment, je crois qu'on devrait placer une emphase accrue sur les données d'offres dans nos prochaines formations - que ce soit à la matinée numérique, à Pacific Contact ou à ArtsReach.

Cependant, je me demande : quelle(s) recommandation(s) devrions-nous formuler à l'intention des participants à nos formations et aux personnes qui consultent la documentation d'Artsdata?. Il faut identifier des recommandations simples et facilement applicables, sinon personne ne les mettra en oeuvre.

• Dans les cas où il n'y a qu'une seule offre (c.-à-d., un seul prix pour tous les billets d'une même représentation), la modélisation recommandée par Google est relativement simple. On pourrait la recommander telle quelle (avec les six propriétés suggérées par Google).

• Dans les cas où il y a plusieurs offres, ça peut rapidement devenir très chronophage pour l'organisateur de l'événement de saisir chaque offre individuelle ET de faire les mises à jour de la valeur de offers.availability pour chaque offre. Il ne serait donc pas raisonable de recommander à un organisateur d'événement l'approche préconisée par Google ("A nested Offer, one for each ticket type") – c'est au service de billetterie en ligne que devrait revenir la tâche de saisir et de maintenir à jour des données structurées d'une telle granularité.

Dans les cas où il y a plusieurs offres pour une même représentation, j'envisage deux recommandations raisonables pour un organisateur d'événement :

1. Imbriquer une seule entité de type Offer, s'assurer d'y inclure l'URL de la billetterie mais ne pas préciser le prix.
2. Imbriquer une entité de type AggregateOffer plutôt que Offer, s'assurer d'y inclure l'URL de la billetterie, y préciser le highPrice et lowPrice mais sans toutefois détailler chaque offre individuelle.
   • À titre d'information, j'ai retrouvé dans le Github de Schema une discussion où AggregateOffer est proposée sans offres associées.

Le scénario 1 est simple, mais l'absence du prix prive le consommateur d'une information importante pour sa prise de décision.
Le scénario 2 introduit un élément de complexité mais il fournit une échelle de prix qui peut aider le consommateur dans sa prise de décision.

@saumier Est-ce que des données modélisées selon le scénario 2 serait exploitables par La Vitrine et par les utilisateurs du CMS Footlight?

[fjjulien]

À titre d'information, j'ai abordé ce sujet avec @dlh28 et Émilie. Elles sont toutes les deux d'avis qu'il n'est pas raisonable de proposer une stratégie qui exigerait de la part de l'organisateur de faire des mises à jour des données structurées d'offres : il faut leur proposer une stratégie de modélisation n'exigeant qu'une seule saisie initiale (à moins que le spectacle soit "sold out", dans quel cas une mise à jour serait nécessaire, tant dans le contenu texte de la page que dans les données structurées).

[fjjulien]

J'ai consulté @christianroy à ce sujet ce matin. Il partage les opinions de Dessa et Émilie quant à l'effort de saisie raisonable que l'on peut demander à un organisateur d'événement. Il estime que la modélisation avec AggregateOffer sans offres individuelles est techniquement correcte et exempte d'erreurs. Il se questionne cependant sur la compatibilité de cette stratégie avec les recommandations de Google, qui suggère la propriété price :

The lowest available price available for your tickets, including service charges and fees. Don't forget to update it as prices change or tickets sell out.

If the event is available without payment, fees, or service charges, set the price to 0.

En même temps, Christian est d'avis que la qualité des données d'offres est un problème mineur si l'on considère le nombre de sites web qui ne satisfont toujours pas à l'exigence de publier « une page web par événement ».