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

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

From: Nick Halliday <nick.halliday@digital.cabinet-office.gov.uk>
Date: Fri, 14 Jul 2017 16:23:48 +0100
Message-ID: <CAEKDZu_2ezor1L1GuCxQOH_5rPeTO=_e59pF95_s=a-=4tpD5g@mail.gmail.com>
To: Leigh Dodds <leigh.dodds@theodi.org>
Cc: public-openactive@w3.org

thank you for all your work so far and patience. I am content to proceed to
"Final Specification" status subject to changes already detailed above.



Open Data

Data Strategy and Governance, Government Digital Service

E: nick.halliday@digital.cabinet-office.gov.uk

M: 07827 992827

On 14 July 2017 at 16:08, Leigh Dodds <leigh.dodds@theodi.org> wrote:

> 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
Received on Friday, 14 July 2017 15:26:19 UTC

This archive was generated by hypermail 2.3.1 : Friday, 14 July 2017 15:26:19 UTC