W3C home > Mailing lists > Public > public-openactive@w3.org > July 2017

Re: Moving Modelling Opportunity data to Final Specification - a request

From: Nick Bailey <nick@makesweat.com>
Date: Thu, 13 Jul 2017 20:07:51 +0100
To: Nick Evans <nick@nickevans.io>, public-openactive@w3.org
Cc: Leigh Dodds <leigh.dodds@theodi.org>
Message-ID: <94983302-4883-b9cd-f93f-748627aac2e8@makesweat.com>
Hi Leigh,

Great progress! We at Makesweat are delighted to be one of the initial 
data publishers.

I thought it might be useful to share our recent experience of working 
with the spec and an implementation in light of Nick's comments; 
certainly not with the depth of knowledge that Nick has around 
standards, so excuse me if my comments are a bit layman!

  * I strongly support the 'complete example' proposal. In practice
    organisations want to get as close to publish-ready as quickly as
    possible (reducing the cost of coming onboard), and building a
    look-alike data extract against the 'example' is really helpful. A
    'hello world' if you like. I'd suggest the main example be designed
    for clarity, hitting 80% of the likely providers rather than every
    edge case (i.e. avoid sub-events, as that sounds conceptually more
  * Agree with Nick's definition of organizer as the person who's
    ultimately delivering the opportunity. Makesweat's opportunities are
    delivered by our customers; uniquely identifiable third parties -
    amateur sports clubs, yoga studios, etc.
  * Agree to remove heightrange and weightrange. I'm pretty sure we'd
    never include this in our data. It feels edge-case; at that level of
    granularity, I'd expect the opportunity description to take over.



On 13/07/2017 19:38, Nick Evans wrote:
> Hi Leigh,
> Thanks for this. Actually this call for questions/comments has come at 
> a really good time as I've just been helping with 10 of these 
> implementations.
> Overall the spec is fantastic, and really fits well with the data 
> being exposed from these systems!
> I've spent some time thinking about the suggestions below, as I 
> understand we want to get this specification signed off ASAP. The 
> experience of the last month has led me to believe that we are "not 
> quite there yet", but with a few quick tweaks we could easily be.
> The following have semantic significance and/or affect both data 
> providers and consumers in their interpretation:
> *1) I propose that the specification should be /slightly/ more 
> complete - to include Offer, identifier, and subEvent*
> Rationalle
>  1. Given the significance of Offers (including fields such as price),
>     and their use in every implementation so far, I would suggest
>     including these explicitly in the modelling specification.
>       * I understand we don't want to crowd the specification with
>         schema.org <http://schema.org> references, but given we've
>         already imported info on "Place" into the specification, and
>         "maximumAttendeeCapacity", and that "Offer" is of equal
>         significance, I'd suggest we aim to include the fundamental
>         building blocks in the specification as the minimum.
>  2. The specification is very loose if much focussed is placed on "use
>     any of schema.org <http://schema.org>" for the fundamentals. This
>     makes it difficult for a data providers and data consumer to cater
>     for all potential scenarios. If a developer was given a brief to
>     "write an application to consume data that conforms to this
>     specification", they would be faced with either (a) expanding the
>     scope of their application to include much of schema.org
>     <http://schema.org> that they thought could be used by providers,
>     which makes the project unwieldy (b) missing out valuable data
>     (such as Offer) or (c) using all the existing endpoints to check
>     what bits of schema.org <http://schema.org> have been used, how
>     they have been interpreted, and making a best guess at de facto
>     standards.
>  3. Having to read the namespace, the specification, the primer, and
>     schema.org <http://schema.org> to implement either a producer or
>     consumer can make the task of complex - the specification should
>     reference core fields, and the primer expand on their use.
>  4. We have a core set of properties emerging and without this being
>     documented in a single place, and considering how vast schema.org
>     <http://schema.org> is, it is difficult for data consumers (and
>     providers) to know what to implement. This is especially true as
>     current guidance is to leave properties out if not relevant for a
>     particular item, instead of setting them to null.
> Recommendation
>   * Include the following in the specification (which have been used
>     most of the last 10 implementations, following your recommendation):
>       o *Offer* (including at a minimum name, price, and
>         priceCurrency; and ideally description also)
>       o "*identifier*" vs. "*id*"
>           + When should either be used, and how do we use them to
>             reference events in other feeds
>           + We should encourage providers to include an identifier/id
>             on as many types as possible to aid data consumers in
>             optimising their reading of the data (dedup, linking the
>             data, etc).
>       o *subEvent* (including the expected behaviour re: inheritance)
> *
> *
> *2) I propose that the "organizer" be defined more specifically*
> *
> *
> Rationalle
>  1. For the "organizer" to be displayed consistently in data
>     consumer's applications, there should be a consistency in the
>     definition we're expecting.
>  2. For an application to decide whether it should trust / approve a
>     particular organizer, what qualifies as an "organizer" should be
>     well defined.
>  3. The organizer definition is currently very broad, which will lead
>     to inconsistent implementations.
> Recommendation
>  1. The "organizer" to be more tightly defined as the "/person or
>     organisation ultimately responsible for the Event/", for example:
>       * For events in a Better or Fusion gym, the organizer should
>         detail Better or Fusion (with HQ contact details).
>       * For "user generated" events in a booking system such a
>         Bookwhen, the organizer should be the account the events were
>         created under. For example for a "((BOUNCE))" session, the
>         organizer should be the organisation ((BOUNCE)) and not
>         Bookwhen nor the instructor of the session (the instructor can
>         be specified under "leader" or "contributor").
>       * For events in Our Parks, the organizer should be "Our Parks"
>       * For franchised events (e.g. Clubbercise) the organiser should
>         be the franchisee, and not the HQ, as they are ultimately
>         responsible for that event.
>  2. There should be a notion of a "unique ID" of an organizer to allow
>     it to be uniquely referenced, even if this is loosely recommended
>     in this version of the spec under the "id" or "identifier" fields.
> *
> *
> *3) I propose that we include a complete example*
> Rationalle
>  1. A number of people have asked for a "complete example" to be
>     provided that covers all cases in one, to help them in implementing.
>  2. In helping with many implementations, I've found myself creating
>     this "complete example" as a crib sheet - happy to share this
>     wherever makes sense.
> Recommendation
>  1. Although it might make sense to have a complete "crib sheet" live
>     outside the specification (a living document of sorts?) it would
>     greatly aid the readability of the spec to have a clear heading of
>     "Complete Example" with an example included there.
> *4) I** propose that we r**emove or demote heightRange and weightRange*
> Rationalle
>  1. As an observation: implementations to date have touched all parts
>     of the spec except for heightRange and weightRange.
>  2. We have yet to come across an opportunity data source that contain
>     this data
>  3. In the interests of keeping the specification minimal and without
>     these properties having been tested in the wild, should they be
>     removed or demoted?
>  4. Potential issues <https://github.com/openactive/ns-beta/issues/3>
>     we've found with distance (regarding consistency of min and max
>     values with schema.org <http://schema.org>) may also apply here,
>     though we won't know until they are tested more thoroughly
> Recommendation
>  1. Move heightRange and weightRange into the beta namespace, and then
>     consider them for inclusion in the spec after they have been
>     road-tested more thoroughly.
> There are a few other minor suggestions, but these are generally typos 
> etc, and I have raised these as issues 
> <https://github.com/openactive/modelling-opportunity-data/issues> 
> instead of detailing them here.
> Hope this helps! Really excited to see this published, as it's such a 
> great step forward for the sector!
> Thanks,
> Nick
> On Mon, Jul 10, 2017 at 9:38 AM, Leigh Dodds <leigh.dodds@theodi.org 
> <mailto:leigh.dodds@theodi.org>> wrote:
>     Hi,
>     As discussed in our recent calls I'm keen to move the Modelling
>     Opportunity Data spec [1] and vocabulary [2] to "Final
>     Specification" status at the W3C.
>     I believe the specification is now stable and has been
>     successfully implemented by a number of publishers. We can
>     continue to improve it further but I'd like to reach this
>     milestone before moving on to further work.
>     The only area that may need some updates is around the handling of
>     recurring events. We have been in discussion with Schema.org for
>     some time, about a proposed set of changes [2] to cover this use
>     case. I've been waiting on approval for that proposal before
>     moving forward.
>     However, if that doesn't move ahead shortly, then we'll need to
>     revise our specifications to define the relevant properties. These
>     will be minor changes to just document the properties that we're
>     already recommending people use [4].
>     The W3C process for publication is quite straight-forward. However
>     I believe I need to be able to demonstrate that the community is
>     happy with the deliverables and is ready to move forward for
>     publication.
>     Can I ask that if you're happy with the specifications moving to
>     "Final Specification" status, pending resolution of the above
>     issue, that you reply to this email with a "+1" or "I approve"
>     message.
>     Having the approval on a public list will help demonstrate support.
>     Similarly, if you have concerns or questions, then please share
>     them with the group so we can work through them.
>     Cheers,
>     L.
>     [1]. https://www.openactive.io/modelling-opportunity-data/
>     <https://www.openactive.io/modelling-opportunity-data/>
>     [2]. https://www.openactive.io/ns/ <https://www.openactive.io/ns/>
>     [3].
>     https://github.com/schemaorg/schemaorg/issues/1457#issuecomment-314039005
>     <https://github.com/schemaorg/schemaorg/issues/1457#issuecomment-314039005>
>     [4].
>     https://github.com/schemaorg/schemaorg/issues/1457#issuecomment-286423792
>     <https://github.com/schemaorg/schemaorg/issues/1457#issuecomment-286423792>
>     -- 
>     Leigh Dodds, Senior Consultant, theODI.org
>     @ldodds
>     The ODI, 65 Clifton Street, London EC2A 4JE
Received on Thursday, 13 July 2017 19:08:23 UTC

This archive was generated by hypermail 2.3.1 : Thursday, 13 July 2017 19:08:24 UTC