- 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
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 <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