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

Hi,

Thanks for all the support and feedback so far. I've incorporated the
suggestions from this thread plus the corrections referenced in github and
sent to me directly to create a new Editors Draft.
This is now available at:

https://www.openactive.io/modelling-opportunity-data/EditorsDraft/

If anyone has further comments, or just wants to indicate support for
moving forward, then please reply to this email. The changes include:

* removing height/weightRange
* adding references to Offer which is now in use by some implementations
* minor revisions to the section on identifiers and adding @id and
schema:identifier to the list of properties in more sections of the
specification
* minor typos and corrections to the examples and introduction

I'm waiting on our proposed changes to Schema.org [1] to be accepted, which
I hope will be handled in the next week or so. My plan will then be to:

* update the specification and namespace to refer to the new schema.org
terms
* apply any additional corrections I've received from you all
* publish the Editors draft as our Latest public draft
* trigger the W3C process for moving to Final Specification

I still have some revisions to make to the primer, including providing a
more complete example as suggested by Nick Evans and Nick Bailey. The
examples will also get published separately to github to make it easier to
share and reuse individual examples

We also aware we still need to move forward on the activity list
discussion. Thanks to those that have provided feedback on that so far.
I've been prioritising wrapping up this specification first, but plan to
schedule some more calls on that in the next few weeks.

Cheers,

L.

[1]. https://github.com/schemaorg/schemaorg/pull/1693

On 13 July 2017 at 20:07, Nick Bailey <nick@makesweat.com> wrote:

> 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 difficult).
>    - 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.
>
>   Cheers!
>
>     Nick
>
> 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 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#issu
>> ecomment-286423792
>>
>> --
>> Leigh Dodds, Senior Consultant, theODI.org
>> @ldodds
>> The ODI, 65 Clifton Street, London EC2A 4JE
>>
>>
>
>


-- 
Leigh Dodds, Senior Consultant, theODI.org
@ldodds
The ODI, 65 Clifton Street, London EC2A 4JE