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

 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 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" 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
   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 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 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 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):
      - *Offer* (including at a minimum name, price, and priceCurrency; and
      ideally description also)
      - "*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).
         - *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) 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> 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/
> [2]. https://www.openactive.io/ns/
> [3]. https://github.com/schemaorg/schemaorg/issues/1457#issuecomm
> ent-314039005
> [4]. https://github.com/schemaorg/schemaorg/issues/1457#
> issuecomment-286423792
>
> --
> Leigh Dodds, Senior Consultant, theODI.org
> @ldodds
> The ODI, 65 Clifton Street, London EC2A 4JE
>
>