diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 9e8af508..ce5be298 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -12,6 +12,7 @@
## Using data
+* [How to find opportunity data using the OpenActive Opportunity Data Dashboard](using-data/how-to-find-opportunity-data-using-the-openactive-opportunity-data-dashboard.md)
* [Harvesting opportunity data](using-data/harvesting-opportunity-data.md)
## Data Model
@@ -56,6 +57,8 @@
* [SportsActivityLocation](data-model/types/sportsactivitylocation.md)
* [Toilets](data-model/types/toilets.md)
* [Towels](data-model/types/towels.md)
+* [Tutorial: describing events using the OpenActive data model - part one: the basics](data-model/tutorial-describing-events-using-the-openactive-data-model-part-one-the-basics.md)
+* [Tutorial: describing events using the OpenActive data model - part two: adding additional detail](data-model/tutorial-describing-events-using-the-openactive-data-model-part-two-adding-additional-detail.md)
## Specifications
diff --git a/docs/data-model/tutorial-describing-events-using-the-openactive-data-model-part-one-the-basics.md b/docs/data-model/tutorial-describing-events-using-the-openactive-data-model-part-one-the-basics.md
new file mode 100644
index 00000000..a4f44e07
--- /dev/null
+++ b/docs/data-model/tutorial-describing-events-using-the-openactive-data-model-part-one-the-basics.md
@@ -0,0 +1,322 @@
+# Tutorial: describing events using the OpenActive data model - part one: the basics
+
+Whether you’re aiming to publish open opportunity data or to use it, familiarity with the OpenActive data model will be key.
+
+
+In this tutorial we’ll be looking at how to describe an activity session using the standard data model we have developed with the community. The model described here will conform to the [Modelling Opportunity Data 2.0](https://www.openactive.io/modelling-opportunity-data/) specification. If you want to jump ahead for a sneak peek of the final version, you can find it in [the validator](https://validator.openactive.io/?url=https%3A%2F%2Fwww.openactive.io%2Fdata-models%2Fversions%2F2.x%2Fexamples%2Ftutorials%2Fdescribing-events%2Fpart-one-finished.json&version=2.0). We’ll cover all of the core properties that are [required](https://www.openactive.io/modelling-opportunity-data/#required-and-optional-properties) as part of the standards.
+
+
+The tutorial covers:
+
+
+* Understanding what the model is
+* The format of a model
+* How to describe a basic activity session
+* Where to go next
+
+By the end of this tutorial you should understand the concept behind the model, and be confident in describing your own events.
+
+
+This tutorial requires a general understanding of JSON, and use of a text editor if you wish to follow along or write your own examples.
+
+## **1. Understanding the data model**
+
+Before jumping in to create one, we first need to understand what we’re trying to create.
+
+
+OpenActive is working to bring about change within the sport and physical activity sector by improving access to ‘open opportunity data’. This means making data about where and when sport and physical activities happen open for anyone to access, use and share. By doing this, more places, products and services can better inform people of opportunities to get active.
+
+
+All of the following types of data can be published as open data, and collectively this is known as opportunity data:
+
+
+* descriptions and lists of physical activities
+* details of the locations and venues at which activities or events takes place
+* the facilities available at those locations
+* the details of event involving physical activities e.g. when and where they will take place, restrictions on attendance, costs, etc
+* any related information, e.g. about the format of the event, its organisers, etc
+
+Having a consistent format is important because it makes it easier for everyone to publish and use data, and so we have standards. [Open standards](https://standards.theodi.org/introduction/what-are-open-standards-for-data/) for data are documented, reusable agreements that help people and organisations to publish, access, share and use better quality data.
+
+
+The data model that we’re going to walk through in this tutorial is an example of following the standards that the community have defined. It builds on existing standards \(such as [schema.org](https://schema.org/), JSON-LD, and [Simple Knowledge Organization System \(SKOS\)](https://www.w3.org/2004/02/skos/)\), which has let us focus specifically on the aspects of describing opportunity data that are important to the physical activity sector.
+
+
+## **2. The format of a model**
+
+The recommended approach to publishing open opportunity data is as JSON, and specifically as JSON-LD \(a JSON-based serialization for linked data\). The use of JSON-LD for sharing structured information is also encouraged by people including [Google](https://developers.google.com/search/docs/guides/intro-structured-data), and is an example of why it’s useful to have common approaches. In this tutorial all of our examples will be using JSON-LD format.
+
+
+## **3. How to describe an activity session**
+
+### **3.1 Add a context**
+
+For our starting foundations, all opportunity data should begin with a context contained within an opening and closing bracket \(see below\).
+
+```text
+{
+"@context": "https://openactive.io/ns/oa.jsonld"
+}
+```
+
+A JSON-LD context maps the terms used in a JSON document to their standard definitions. To indicate that your data conforms to the OpenActive opportunity data specification, include a @context reference that matches the above.
+
+****
+
+### **3.2 Adding basic session details**
+
+Now we can start to add in the information about the session itself. To illustrate this, we’re going to use a rollerblading fitness class.
+
+
+The following are the minimum requirements for modelling opportunity data:
+
+
+* define that it’s an event \(opportunity\)
+* its name
+* a URL providing a link to a web page describing the session
+* an indication of the type of activity that will take place at an event
+* the time at which the event will take place
+* the location at which the event will take place
+* the person or organisation responsible for running the event
+
+Whilst this tutorial will help you to understand what’s necessary to get a basic, validating opportunity, there’s a lot more that you can do with the data. Other fields are optional, but might be recommended as they provide useful information for participants. Generally we encourage people to provide as much useful information as possible, while respecting privacy. We’ll talk a bit more about this in the second half of this tutorial, or you can refer to the [Required and Optional properties](https://www.openactive.io/modelling-opportunity-data/#required-and-optional-properties) part of the specification.
+
+
+Let’s walk through and build it up.
+
+
+#### **Defining the type of resource**
+
+Adding to the JSON-LD context that we added in the first step, we now want to start describing the event itself.
+
+To describe what type of thing we're going to be sharing in our data, we need to add a type property. It’s possible for the data model to describe a number of different types of things, but as we're describing an Event we’ll use that as the value.
+
+```text
+{
+"@context": "https://openactive.io/ns/oa.jsonld",
+"type": "Event"
+}
+```
+
+#### **Give it a name and URL**
+
+Add in the name for your individual session, and the public URL where someone could go to find more information, or perhaps sign up to participate.
+
+```text
+{
+ "@context": "https://openactive.io/ns/oa.jsonld",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1"
+}
+```
+
+#### **Defining the activity type**
+
+Next, we want to describe the type of activity this opportunity is for. As part of the OpenActive standards work there have been some initial efforts to develop a [standardised list of activities](https://www.openactive.io/activity-list/) for the sector. Where possible consider the terminology already being used, but if these don’t accurately reflect your activity types we’d encourage you to share your list as open data and contribute to the efforts in this area.
+
+In this case Roller Blading is in the standardised activity list, so we can add it to our model, along with references to the activity list that it has come from. We do this by adding an array of SKOS Concepts, however for our example we only need to define one activity type:
+
+```text
+{
+ "@context": "https://openactive.io/ns/oa.jsonld",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list/activity-list.jsonld
+"
+ }],
+}
+```
+
+#### **Giving it a time**
+
+People need to know when the event starts, and so in its most basic form we include a startDate property. The value of this must be a valid \[[ISO8601](https://www.openactive.io/opportunity-data-primer/#bib-ISO8601)\] date or date time, with a trailing definition of timezone. For example, 2018-08-01T10:51:02Z or 2018-08-01T10:51:02+01:00.
+
+Whilst this is the only _mandatory_ property, it’s recommended to include information about when the event finishes, and how long the activity part of it takes. Due to this, you may wish to include an EndDate, and a duration.
+
+The endDate property is the partner to startDate, and is used to signify the end of the event. Furthermore, certain activities may have a start and end point, but the actual duration of activity itself may be less than this total period - for instance a bike ride that meets at 10am and concludes at 3pm, but only includes two hours of cycling with the rest as social time. For activities such as these, we may wish to use the duration property \(defined using an [ISO8601](https://www.openactive.io/opportunity-data-primer/#bib-ISO8601) duration\) to indicate the length of the activity within the overall period.
+
+In our example the activity lasts the full hour dictated by the start and end points. For that reason duration is optional, but it has been included here to illustrate usage.
+
+```text
+{
+ "@context": "https://openactive.io/ns/oa.jsonld",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list/activity-list.jsonld
+"
+ }],
+ "startDate": "2018-08-13T20:00:00Z",
+ "endDate": "2018-08-13T21:00:00Z",
+ "duration": "PT1H",
+}
+```
+
+Your event timings may be more complicated than this, and we’ll come onto that in part two of this tutorial.
+
+#### **Stating where it happens**
+
+Finally, people need to know where to go to attend the event. Locations are added to events using the location property, which follows the [schema.org standards for address data](https://schema.org/PostalAddress). The minimum requirements for validation are shown below, but the recommendation in the specification is that applications should provide as much information about the **Place** as possible.
+
+```text
+{
+ "@context": "https://openactive.io/ns/oa.jsonld",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list/activity-list.jsonld
+"
+ }],
+ "startDate": "2018-08-13T20:00:00Z",
+ "endDate": "2018-08-13T21:00:00Z",
+ "duration": "PT1H",
+ "location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ }
+ }
+}
+```
+
+An example of providing more information is through including geocodes. Whilst this is not mandatory for each event, it’s recommended as people are more likely to use the data if it’s geocoded.
+
+```text
+{
+ "@context": "https://openactive.io/ns/oa.jsonld",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list/activity-list.jsonld
+"
+ }],
+ "startDate": "2018-08-13T20:00:00Z",
+ "endDate": "2018-08-13T21:00:00Z",
+ "duration": "PT1H",
+ "location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ }
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+}
+```
+
+**Providing information about the organiser**
+
+And finally, we need to include information about the person or organisation responsible for running the event. With this it’s important to note that personal data must not be published as open data without consent.
+Whilst events could be organised by a club, led by a particular individual, or include other named participants of note, we’ll keep it simple for this first example and just use a club. As always, further detail is available in the [spec](https://www.openactive.io/modelling-opportunity-data/#describing-organisers-code-schema-person-code-and-code-schema-organization-code-) if needed.
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "startDate": "2018-08-13T20:00:00Z",
+ "endDate": "2018-08-13T21:00:00Z",
+ "duration": "PT1H",
+ "location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ }
+ }
+```
+
+And that’s it! Here we have a valid event described according to the OpenActive opportunity data model.
+You’re able to double-check that you’ve got everything entered correctly by pasting your code into the [OpenActive data validator tool](https://validator.openactive.io/), or jump to [this pre-populated example](https://validator.openactive.io/?url=https%3A%2F%2Fwww.openactive.io%2Fdata-models%2Fversions%2F2.x%2Fexamples%2Ftutorials%2Fdescribing-events%2Fpart-one-finished.json&version=2.0).
+
+### **3.2 Changes for v2.1**
+
+v2.1 of the modelling spec will include offers as a required field, as it is critical for data users and end user experience. If you are building your data now we strongly recommend you include this field. Details of how to do this are included in part 2 of this tutorial.
+
+## **4. Where to go next**
+
+This is all you need to get up and running, but it may be that you’d like a bit more detail. If you’ve taken the time to validate the above, you’ll also see that the validator returns a number of additional recommendations for making the data even better. If you’d like to build the example up even further you can follow along with [part two: adding additional timing detail](tutorial-describing-events-using-the-openactive-data-model-part-two-adding-additional-detail.md).
+
+
+Alternatively, if you’d like to jump straight in to creating your own events, the following will probably be useful:
+
+
+* Data model specification: [https://www.openactive.io/modelling-opportunity-data/](https://www.openactive.io/modelling-opportunity-data/)
+* OpenActive developer area: [https://developer.openactive.io/](https://developer.openactive.io/)
+* A “full fat” Event example, which you may want to use as a starting point and cut down where needed: [https://developer.openactive.io/models/event](https://developer.openactive.io/models/event)
+
+Activity list: [https://www.openactive.io/activity-list/](https://www.openactive.io/activity-list/)
+
+
diff --git a/docs/data-model/tutorial-describing-events-using-the-openactive-data-model-part-two-adding-additional-detail.md b/docs/data-model/tutorial-describing-events-using-the-openactive-data-model-part-two-adding-additional-detail.md
new file mode 100644
index 00000000..e1edfb54
--- /dev/null
+++ b/docs/data-model/tutorial-describing-events-using-the-openactive-data-model-part-two-adding-additional-detail.md
@@ -0,0 +1,559 @@
+# Tutorial: describing events using the OpenActive data model - part two: adding additional detail
+
+In the [first part of this tutorial](tutorial-describing-events-using-the-openactive-data-model-part-one-the-basics.md) series we looked at putting together a basic example for an event.
+
+Using our previous example as a starting point we’ll now look at adding additional detail into our model.
+
+This tutorial will cover:
+
+* Detailing more complex event times, including recurring activities
+* How to add in a description and images
+* Revisiting activity types, including multiple activities
+* Defining whether an activity is part of a wider programme
+* Describing suitability
+* Adding in an offer to describe the cost of an activity
+
+As a reminder, here’s our starting point from the previous tutorial:
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "startDate": "2018-08-13T20:00:00Z",
+ "endDate": "2018-08-13T21:00:00Z",
+ "duration": "PT1H",
+ "location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ }
+ }
+```
+
+## **1. Modelling recurring events**
+
+Whilst some events may be a one-off, very commonly others recur on a predictable schedule. Where this happens we can model the schedule rather than having to enter each opportunity individually. We do this through the **eventSchedule** property.
+
+In the below example you’ll see that we’ve removed the previously used **startDate** and **endDate** property, replacing these with an **eventSchedule** block. This details that it’s a \(repeating\) schedule, which starts and ends on specified dates \(leave off the end date if it repeats indefinitely\), and the frequency that repetition of the event should occur. The frequency again uses an ISO8601 duration, and can be \(for example\) daily, weekly, or monthly.
+
+
+We’ve also explicitly stated the **startTime**, **endTime**, and **duration**, and the same logic applies to these as we discussed previously.
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "eventSchedule": [
+ {
+ "type": "Schedule",
+ "startDate": "2018-08-13",
+ "endDate": "2020-08-13",
+ "duration": "PT1H",
+ "repeatFrequency": "P1W",
+ "byDay": [
+ "https://schema.org/Thursday"
+ ],
+ "startTime": "20:00",
+ "endTime": "21:00",
+ "scheduledEventType": "ScheduledSession"
+ }
+ ],
+"location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ }
+ }
+```
+
+## **2. Adding a description**
+
+At present, the only information we’ve built up around the content of the session is its name, activity type, and URL. To give our viewers more to go on and encourage them to attend, we may wish to use something more descriptive, in the form of a description. This is possible by using the property description.
+
+If an event is listed on the web there's probably already a description of some form, and that's the detail that would go in here. We’d suggest things like:
+
+* how the event will be run
+* the types of people who are or will be attending the event
+* information on the event organiser
+* notes on any equipment required
+* suggested apparel, e.g. footwear, kit, etc
+
+Let’s add in our description. It’s important to note that the order of properties is not important, but you may want to consider logical groupings for human readability. We’ve added it under the name and URL for this reason.
+
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "description": "Run by our head instructor, this is an intermediate class for those with existing roller blading experience, where we focus on exercises to tone key muscle groups. Bring your own boots, shape up, and have fun!",
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "eventSchedule": [
+ {
+ "type": "Schedule",
+ "startDate": "2018-08-13",
+ "endDate": "2020-08-13",
+ "duration": "PT1H",
+ "repeatFrequency": "P1W",
+ "byDay": [
+ "https://schema.org/Thursday"
+ ],
+ "startTime": "20:00",
+ "endTime": "21:00",
+ "scheduledEventType": "ScheduledSession"
+ }
+ ],
+"location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ }
+ }
+```
+
+## **3. Enhancing with images**
+
+Another element that can encourage participation is the inclusion of imagery. It’s recommended that you provide images that are representative of your events, and an array allows for the provision of multiple images.
+
+Let’s add a large image and a smaller thumbnail option under our new description.
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "description": "Run by our head instructor, this is an intermediate class for those with existing roller blading experience, where we focus on exercises to tone key muscle groups. Bring your own boots, shape up, and have fun!",
+ "image": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_large.jpg",
+ "thumbnail": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_thumbnail.jpg"
+ }
+ ]
+ }],
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "eventSchedule": [
+ {
+ "type": "Schedule",
+ "startDate": "2018-08-13",
+ "endDate": "2020-08-13",
+ "duration": "PT1H",
+ "repeatFrequency": "P1W",
+ "byDay": [
+ "https://schema.org/Thursday"
+ ],
+ "startTime": "20:00",
+ "endTime": "21:00",
+ "scheduledEventType": "ScheduledSession"
+ }
+ ],
+"location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ }
+ }
+```
+
+## **4. Defining whether an activity is part of a wider programme**
+
+As well as having our opportunity repeat, we may have activities that are part of a wider [Programme](https://www.openactive.io/modelling-opportunity-data/#programmes) of events. These Programmes are often associated with specific branding, for instance: "Les Mills BodyPump" or "Back to Netball".
+
+In our fictional example let’s assume this is the case, and add in an association with a Programme. In its most basic form, we can do this by using the new property programme and adding the required details as follows:
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "description": "Run by our head instructor, this is an intermediate class for those with existing roller blading experience, where we focus on exercises to tone key muscle groups. Bring your own boots, shape up, and have fun!",
+ "image": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_large.jpg",
+ "thumbnail": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_thumbnail.jpg"
+ }
+ ]
+ }],
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "eventSchedule": [
+ {
+ "type": "Schedule",
+ "startDate": "2018-08-13",
+ "endDate": "2020-08-13",
+ "duration": "PT1H",
+ "repeatFrequency": "P1W",
+ "byDay": [
+ "https://schema.org/Thursday"
+ ],
+ "startTime": "20:00",
+ "endTime": "21:00",
+ "scheduledEventType": "ScheduledSession"
+ }
+ ],
+ "programme": {
+ "type": "Brand",
+ "name": "BladeFitness™️",
+ "url": "https://www.exampleorgbody.org/blade-fitness/",
+ "description": "A programme of events to encourage participation and get fit through roller blading"
+ },
+ "location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ }
+ }
+```
+
+Here, we’ve added the name of the programme, a link to further detail about it, and a short description.
+
+
+## **5. Describing suitability**
+
+Next we’ll look at adding in information to describe who your opportunity is suitable for.
+
+People searching for things to do and ways to be active want to feel confident that opportunities are the right ones for them. Where it’s important, we can encourage participation by highlighting inclusion or restrictions as needed. For example, this could cover whether events are:
+
+* suitable for a specific age range
+* suitable for people within a specific height or weight range
+* restricted to a male or female audience, or mixed
+* suitable for people with a certain amount of experience
+* able to provide support for particular disabilities
+
+When you come to writing your own suitability criteria it’s recommended that you refer to the [specification](https://www.openactive.io/modelling-opportunity-data/#describing-the-audience-suitability-of-events) to better understand all of the options available, and what is implied by the inclusion or omission or certain properties.
+
+For our example let’s explicitly state that this is a session for adults, with no gender restriction, at an intermediate level.
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "description": "Run by our head instructor, this is an intermediate class for those with existing roller blading experience, where we focus on exercises to tone key muscle groups. Bring your own boots, shape up, and have fun!",
+ "image": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_large.jpg",
+ "thumbnail": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_thumbnail.jpg"
+ }
+ ]
+ }],
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "eventSchedule": [
+ {
+ "type": "Schedule",
+ "startDate": "2018-08-13",
+ "endDate": "2020-08-13",
+ "duration": "PT1H",
+ "repeatFrequency": "P1W",
+ "byDay": [
+ "https://schema.org/Thursday"
+ ],
+ "startTime": "20:00",
+ "endTime": "21:00",
+ "scheduledEventType": "ScheduledSession"
+ }
+ ],
+ "programme": {
+ "type": "Brand",
+ "name": "BladeFitness™️",
+ "url": "https://www.exampleorgbody.org/blade-fitness/",
+ "description": "A programme of events to encourage participation and get fit through roller blading"
+ },
+ "location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ },
+ "ageRange": {
+ "type": "QuantitativeValue",
+ "minValue": 18
+ },
+ "genderRestriction": "https://openactive.io/NoRestriction",
+ "level": [
+ "intermediate"
+ ]
+}
+```
+
+## **6. Adding offers**
+
+Some opportunities are freely available for anyone to attend, but where participants need to pay for an event we can use Offers.
+
+In our final amendment to this example, we’ll add some detail that shows our class has an individual cost of £10 per session.
+
+```text
+{
+ "@context": "https://openactive.io/",
+ "type": "Event",
+ "name": "Blade and tone",
+ "url": "http://www.example.org/events/1",
+ "description": "Run by our head instructor, this is an intermediate class for those with existing roller blading experience, where we focus on exercises to tone key muscle groups. Bring your own boots, shape up, and have fun!",
+ "image": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_large.jpg",
+ "thumbnail": [
+ {
+ "type": "ImageObject",
+ "url": "https://example.com/static/image/yourimage_thumbnail.jpg"
+ }
+ ]
+ }],
+ "activity": [{
+ "id":"
+https://openactive.io/activity-list/#7e5cb3ee-8c91-4f85-8c97-e335e0013eb3
+",
+ "type": "Concept",
+ "prefLabel": "Roller blading",
+ "inScheme": "
+https://openactive.io/activity-list
+"
+ }],
+ "eventSchedule": [
+ {
+ "type": "Schedule",
+ "startDate": "2018-08-13",
+ "endDate": "2020-08-13",
+ "duration": "PT1H",
+ "repeatFrequency": "P1W",
+ "byDay": [
+ "https://schema.org/Thursday"
+ ],
+ "startTime": "20:00",
+ "endTime": "21:00",
+ "scheduledEventType": "ScheduledSession"
+ }
+ ],
+ "programme": {
+ "type": "Brand",
+ "name": "BladeFitness™️",
+ "url": "https://www.exampleorgbody.org/blade-fitness/",
+ "description": "A programme of events to encourage participation and get fit through roller blading"
+ },
+ "location": {
+ "type": "Place",
+ "name": "ExampleCo Gym",
+ "address": {
+ "type": "PostalAddress",
+ "streetAddress": "1 High Street",
+ "addressLocality": "Colchester",
+ "addressRegion": "Essex",
+ "postalCode": "AB1 2CD",
+ "addressCountry": "GB"
+ },
+ "geo": {
+ "type": "GeoCoordinates",
+ "latitude": 51.88805,
+ "longitude": 0.90286
+ }
+ },
+ "organizer": {
+ "name": "Colchester Bladers",
+ "type": "Organization",
+ "url": "https://www.examplecluburl.com"
+ },
+ "ageRange": {
+ "type": "QuantitativeValue",
+ "minValue": 18
+ },
+ "genderRestriction": "https://openactive.io/NoRestriction",
+ "level": [
+ "intermediate"
+ ],
+ "offers": [{
+ "type": "Offer",
+ "name": "Single session",
+ "price": 10,
+ "priceCurrency": "GBP"
+ }]
+}
+```
+
+As in the previous tutorial we can check that this validates by either copying and pasting the above code into the [validation tool](https://validator.openactive.io), or using [this pre-populated link](https://validator.openactive.io/?url=https%3A%2F%2Fwww.openactive.io%2Fdata-models%2Fversions%2F2.x%2Fexamples%2Ftutorials%2Fdescribing-events%2Fpart-two-finished.json&version=2.0).
+
+## **7. Where to go next**
+
+At this point you should understand some of the more advanced ways to describe events using the OpenActive data model. To continue on your journey, please refer to the following resources if you’d like more information.
+
+* Data model specification: [https://www.openactive.io/modelling-opportunity-data/](https://www.openactive.io/modelling-opportunity-data/)
+* Primer: [https://www.openactive.io/opportunity-data-primer/](https://www.openactive.io/opportunity-data-primer/)
+* Activity list: [https://www.openactive.io/activity-list/](https://www.openactive.io/activity-list/)
+
+
+
diff --git a/docs/data-model/types/courseinstance.md b/docs/data-model/types/courseinstance.md
index 434844f7..027eaabf 100644
--- a/docs/data-model/types/courseinstance.md
+++ b/docs/data-model/types/courseinstance.md
@@ -55,13 +55,22 @@ This type is derived from [https://pending.schema.org/CourseInstance](https://pe
The name of the event
Example
"name": "Speedball"
+
+ | offers |
+
+ Array of Offer
+ |
+
+ An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
+ |
+
| organizer |
Organization
- or -
Person
|
- The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": [
{
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
]
+ The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
@@ -79,7 +88,7 @@ This type is derived from [https://pending.schema.org/CourseInstance](https://pe
### ** Required options **
-While these properties are marked as optional, a data publisher must provide either a schema:startDate or specify a oa:eventSchedule for an event.
+While these properties are marked as optional in the specification, a data publisher must provide either a `startDate` or specify an `eventSchedule` for an event.
@@ -192,7 +201,7 @@ While these properties are marked as optional, a data publisher must provide eit
Array of Person
- Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
+ Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"gender": "https://schema.org/Male",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
|
@@ -213,15 +222,6 @@ While these properties are marked as optional, a data publisher must provide eit
The maximum capacity of the Event.
Example
"maximumAttendeeCapacity": 30
-
- | offers |
-
- Array of Offer
- |
-
- An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
- |
-
| remainingAttendeeCapacity |
diff --git a/docs/data-model/types/event.md b/docs/data-model/types/event.md
index bfc679e5..29d47fd3 100644
--- a/docs/data-model/types/event.md
+++ b/docs/data-model/types/event.md
@@ -55,13 +55,22 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
The name of the event Example "name": "Speedball"
|
+
+ | offers |
+
+ Array of Offer
+ |
+
+ An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
+ |
+
| organizer |
Organization
- or -
Person
|
- The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": [
{
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
]
+ The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
@@ -79,7 +88,7 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
### ** Required options **
-While these properties are marked as optional, a data publisher must provide either a schema:startDate or specify a oa:eventSchedule for an event.
+While these properties are marked as optional in the specification, a data publisher must provide either a `startDate` or specify an `eventSchedule` for an event.
@@ -192,7 +201,7 @@ While these properties are marked as optional, a data publisher must provide eit
Array of Person
- Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
+ Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"gender": "https://schema.org/Male",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
|
@@ -213,15 +222,6 @@ While these properties are marked as optional, a data publisher must provide eit
The maximum capacity of the Event.
Example
"maximumAttendeeCapacity": 30
-
- | offers |
-
- Array of Offer
- |
-
- An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
- |
-
| remainingAttendeeCapacity |
diff --git a/docs/data-model/types/eventseries.md b/docs/data-model/types/eventseries.md
index 7f3bc1b4..8ae0da99 100644
--- a/docs/data-model/types/eventseries.md
+++ b/docs/data-model/types/eventseries.md
@@ -52,16 +52,42 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
Organization
- or -
Person
|
- The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": [
{
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
]
+ The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
+
+
+
+
+### ** Required options **
+
+An `id` and/or `identifier` must be provided in order to allow data users to group `EventSeries` together consistently.
+
+
+
- | url |
+ Property |
+ Expected Type |
+ Description |
+
+
+
+
+ | id |
url
|
- A URL to a web page (or section of a page) that describes the event. Example "url": "https://example.com/event/1234"
+ A unique url based identifier for the record Example "id": "https://example.com/event/12345"
+ |
+
+
+ | identifier |
+
+ Text
- or -
PropertyValue
- or -
Array of PropertyValue
- or -
Integer
+ |
+
+ A local non-URI identifier for the resource Example "identifier": "SB1234"
|
@@ -106,15 +132,6 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
A free text description of the event
Example
"description": "An fast paced game that incorporates netball, handball and football."
-
- | eventStatus |
-
- EventStatusType
- |
-
- The status of an event. Can be used to indicate rescheduled or cancelled events Example "eventStatus": "https://schema.org/EventScheduled"
- |
-
| genderRestriction |
@@ -134,12 +151,12 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
|
- | leader |
+ isCoached |
- Array of Person
+ Boolean
|
- Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
+ A boolean property that indicates whether an Event will be coached. This flag allows an Event to be marked as being coached without having to specify a named individual as a coach. This addresses both privacy concerns and also scenarios where the actual coach may only be decided on the day. Example "isCoached": "true"
|
@@ -152,30 +169,12 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
- | maximumAttendeeCapacity |
-
- Integer
- |
-
- The maximum capacity of the Event. Example "maximumAttendeeCapacity": 30
- |
-
-
- | offers |
-
- Array of Offer
- |
-
- An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
- |
-
-
- | remainingAttendeeCapacity |
+ programme |
- Integer
+ Brand
|
- The number of places that are still available for the Event. Example "remainingAttendeeCapacity": 20
+ Indicates that an event will be organised according to a specific Programme. Example "programme": {
"type": "Brand",
"name": "Play Ball!",
"url": "http://example.org/brand/play-ball"
}
|
@@ -274,6 +273,15 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
A an array of oa:Schedule or oa:PartialSchedule, which represents a recurrence pattern.
Example
"eventSchedule": [
{
"type": "PartialSchedule",
"repeatFrequency": "P1W",
"startTime": "20:15",
"endTime": "20:45",
"byDay": [
"http://schema.org/Tuesday"
]
}
]
+
+ | eventStatus |
+
+ EventStatusType
+ |
+
+ The status of an event. Can be used to indicate rescheduled or cancelled events Example "eventStatus": "https://schema.org/EventScheduled"
+ |
+
| identifier |
@@ -293,12 +301,12 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
|
- | isCoached |
+ leader |
- Boolean
+ Array of Person
|
- A boolean property that indicates whether an Event will be coached. This flag allows an Event to be marked as being coached without having to specify a named individual as a coach. This addresses both privacy concerns and also scenarios where the actual coach may only be decided on the day. Example "isCoached": "true"
+ Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"gender": "https://schema.org/Male",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
|
@@ -310,6 +318,15 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
The location at which the event will take place. Or, in the case of events that may span multiple locations, the initial meeting or starting point.
It is recommended that locations should be specified as a Place complete with a fully described geographic location and/or address.If only an address is available then this should be described as a PostalAddress.
Applications may use schema:Text to provide a more general description of a location ("In Victoria Park, near the lake"), but this is not recommended: consuming applications will be unable to help users discover opportunities based on their location.
Example
"location": {
"address": {
"addressLocality": "New Malden",
"addressRegion": "London",
"postalCode": "NW5 3DU",
"streetAddress": "Raynes Park High School, 46A West Barnes Lane",
"type": "PostalAddress"
},
"description": "Raynes Park High School in London",
"geo": {
"latitude": 51.4034423828125,
"longitude": -0.2369088977575302,
"type": "GeoCoordinates"
},
"id": "https://example.com/locations/1234ABCD",
"identifier": "1234ABCD",
"name": "Raynes Park High School",
"telephone": "01253 473934",
"type": "Place"
}
+
+ | maximumAttendeeCapacity |
+
+ Integer
+ |
+
+ The maximum capacity of the Event. Example "maximumAttendeeCapacity": 30
+ |
+
| meetingPoint |
@@ -319,6 +336,15 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
Instructions for the attendees of an Event about where they should meet the organizer or leader at the start of the event. Some larger locations may have several possible meeting points, so this property provides additional more specific directions. Example "meetingPoint": "At the entrance to the park"
|
+
+ | offers |
+
+ Array of Offer
+ |
+
+ An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
+ |
+
| potentialAction |
@@ -329,12 +355,12 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
|
- | programme |
+ remainingAttendeeCapacity |
- Brand
+ Integer
|
- Indicates that an event will be organised according to a specific Programme. Example "programme": {
"type": "Brand",
"name": "Play Ball!",
"url": "http://example.org/brand/play-ball"
}
+ The number of places that are still available for the Event. Example "remainingAttendeeCapacity": 20
|
@@ -373,6 +399,15 @@ This type is derived from [https://pending.schema.org/EventSeries](https://pendi
Relates a child event to a parent event. Properties describing the parent event can be assumed to apply to the child, unless otherwise specified. A parent event might specify a recurring schedule, of which the child event is one specific instance
+
+ | url |
+
+ url
+ |
+
+ A URL to a web page (or section of a page) that describes the event. Example "url": "https://example.com/event/1234"
+ |
+
diff --git a/docs/data-model/types/facilityuse.md b/docs/data-model/types/facilityuse.md
index c9e80ea3..a0d843b4 100644
--- a/docs/data-model/types/facilityuse.md
+++ b/docs/data-model/types/facilityuse.md
@@ -61,7 +61,7 @@ description: This page describes the FacilityUse type.
- The organisation responsible for providing the facility
+ The organisation responsible for providing the facility Example "provider": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
diff --git a/docs/data-model/types/headlineevent.md b/docs/data-model/types/headlineevent.md
index 0e5406ab..b1b4e3a1 100644
--- a/docs/data-model/types/headlineevent.md
+++ b/docs/data-model/types/headlineevent.md
@@ -61,7 +61,7 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
Organization
- or -
Person
- The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": [
{
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
]
+ The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
@@ -166,7 +166,7 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
Array of Person
- Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
+ Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"gender": "https://schema.org/Male",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
|
diff --git a/docs/data-model/types/individualfacilityuse.md b/docs/data-model/types/individualfacilityuse.md
index 796fea75..bbab228a 100644
--- a/docs/data-model/types/individualfacilityuse.md
+++ b/docs/data-model/types/individualfacilityuse.md
@@ -61,7 +61,7 @@ description: This page describes the IndividualFacilityUse type.
|
- The organisation responsible for providing the facility
+ The organisation responsible for providing the facility Example "provider": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
diff --git a/docs/data-model/types/organization.md b/docs/data-model/types/organization.md
index 2c7ef789..1293d355 100644
--- a/docs/data-model/types/organization.md
+++ b/docs/data-model/types/organization.md
@@ -112,6 +112,15 @@ This type is derived from [https://schema.org/Organization](https://schema.org/O
The description of the Organization
Example
"description": "The national governing body of cycling"
+
+ | email |
+
+ Text
+ |
+
+ General enquiries e-mail address for the organization. Example "email": "info@example.com"
+ |
+
| identifier |
diff --git a/docs/data-model/types/person.md b/docs/data-model/types/person.md
index 9c59018e..6dc5d6c2 100644
--- a/docs/data-model/types/person.md
+++ b/docs/data-model/types/person.md
@@ -76,6 +76,24 @@ This type is derived from [https://schema.org/Person](https://schema.org/Person)
The description of the Person Example "description": "The leader of the coaching team"
|
+
+ | familyName |
+
+ Text
+ |
+
+ A last name for the person. This person must give direct permission for their personal information to be shared as part of the Open Data. Example "familyName": "Thompson"
+ |
+
+
+ | givenName |
+
+ Text
+ |
+
+ A first name for the person. This person must give direct permission for their personal information to be shared as part of the Open Data. Example "givenName": "Daley"
+ |
+
| identifier |
diff --git a/docs/data-model/types/place.md b/docs/data-model/types/place.md
index 65e2a20c..17beda2e 100644
--- a/docs/data-model/types/place.md
+++ b/docs/data-model/types/place.md
@@ -41,8 +41,10 @@ This type is derived from [https://schema.org/Place](https://schema.org/Place),
|
-### **Recommended fields**
-
+### ** Required options **
+
+While these properties are marked as recommended in the specification, a data publisher must provide as much detail in both `address` and `geo` for an event as possible.
+
@@ -53,48 +55,63 @@ This type is derived from [https://schema.org/Place](https://schema.org/Place),
- | id |
+ address |
- url
+ PostalAddress
- or -
Text
|
- A unique url based identifier for the record Example "id": "https://example.com/place/12345"
+ A structured PostalAddress object for the Place. Ideally the address should be provided using the PostalAddress structured format. Google Reserve requires https://schema.org/PostalAddress and will not accept plain text addresses. Example "address": {
"type": "PostalAddress",
"streetAddress": "Raynes Park High School, 46A West Barnes Lane",
"addressLocality": "New Malden",
"addressRegion": "London",
"postalCode": "NW5 3DU",
"addressCountry": "GB"
}
|
- | address |
+ geo |
- PostalAddress
- or -
Text
+ GeoCoordinates
|
- A structured PostalAddress object for the Place. Ideally the address should be provided using the PostalAddress structured format. Google Reserve requires https://schema.org/PostalAddress and will not accept plain text addresses. Example "address": {
"type": "PostalAddress",
"streetAddress": "Raynes Park High School, 46A West Barnes Lane",
"addressLocality": "New Malden",
"addressRegion": "London",
"postalCode": "NW5 3DU",
"addressCountry": "GB"
}
+ The geo coordinates of the Place. Example "geo": {
"latitude": 51.4034423828125,
"longitude": -0.2369088977575302,
"type": "GeoCoordinates"
}
|
+
+
+
+
+### **Recommended fields**
+
+
+
+
+ | Property |
+ Expected Type |
+ Description |
+
+
+
- | amenityFeature |
+ id |
- Array of LocationFeatureSpecification
+ url
|
- An array listing the Ammenities of the Place. Example "amenityFeature": [
{
"name": "Changing Facilities",
"value": true,
"type": "ChangingFacilities"
},
{
"name": "Showers",
"value": false,
"type": "Showers"
},
{
"name": "Lockers",
"value": true,
"type": "Lockers"
},
{
"name": "Towels",
"value": false,
"type": "Towels"
},
{
"name": "Creche",
"value": false,
"type": "Creche"
},
{
"name": "Parking",
"value": true,
"type": "Parking"
}
]
+ A unique url based identifier for the record Example "id": "https://example.com/place/12345"
|
- | description |
+ amenityFeature |
- Text
+ Array of LocationFeatureSpecification
|
- The description of the Place Example "description": "Raynes Park High School in London"
+ An array listing the Ammenities of the Place. Example "amenityFeature": [
{
"name": "Changing Facilities",
"value": true,
"type": "ChangingFacilities"
},
{
"name": "Showers",
"value": false,
"type": "Showers"
},
{
"name": "Lockers",
"value": true,
"type": "Lockers"
},
{
"name": "Towels",
"value": false,
"type": "Towels"
},
{
"name": "Creche",
"value": false,
"type": "Creche"
},
{
"name": "Parking",
"value": true,
"type": "Parking"
}
]
|
- | geo |
+ description |
- GeoCoordinates
+ Text
|
- The geo coordinates of the Place. Example "geo": {
"latitude": 51.4034423828125,
"longitude": -0.2369088977575302,
"type": "GeoCoordinates"
}
+ The description of the Place Example "description": "Raynes Park High School in London"
|
@@ -148,6 +165,15 @@ This type is derived from [https://schema.org/Place](https://schema.org/Place),
+
+ | address |
+
+ PostalAddress
- or -
Text
+ |
+
+ A structured PostalAddress object for the Place. Ideally the address should be provided using the PostalAddress structured format. Google Reserve requires https://schema.org/PostalAddress and will not accept plain text addresses. Example "address": {
"type": "PostalAddress",
"streetAddress": "Raynes Park High School, 46A West Barnes Lane",
"addressLocality": "New Malden",
"addressRegion": "London",
"postalCode": "NW5 3DU",
"addressCountry": "GB"
}
+ |
+
| containedInPlace |
@@ -166,6 +192,15 @@ This type is derived from [https://schema.org/Place](https://schema.org/Place),
Places that exist within this place Example "containsPlace": {
"type": "Place",
"url": "https://www.everyoneactive.com/centres/Center-Parcs-Sports-Plaza",
"name": "Center Parcs Sports Plaza"
}
|
+
+ | geo |
+
+ GeoCoordinates
+ |
+
+ The geo coordinates of the Place. Example "geo": {
"latitude": 51.4034423828125,
"longitude": -0.2369088977575302,
"type": "GeoCoordinates"
}
+ |
+
| identifier |
diff --git a/docs/data-model/types/schedule.md b/docs/data-model/types/schedule.md
index 9d38742f..77c89bd8 100644
--- a/docs/data-model/types/schedule.md
+++ b/docs/data-model/types/schedule.md
@@ -37,15 +37,6 @@ This type is derived from [https://pending.schema.org/Schedule](https://pending.
The end time of the event. Example "endTime": "12:00:00"
|
-
- | repeatFrequency |
-
- Duration
- |
-
- Defines the frequency at which Events will occur according to a Schedule. The intervals between events should be defined as a Duration of time. Example "repeatFrequency": "P1D"
- |
-
| scheduledEventType |
@@ -70,7 +61,7 @@ This type is derived from [https://pending.schema.org/Schedule](https://pending.
### ** Required options **
-While these properties are marked as optional, a data publisher must provide either a schema:byDay, schema:byMonth or byMonthDay for a schedule.
+While these properties are marked as optional, a data publisher must provide either a `byDay`, `byMonth`, `byMonthDay` or `repeatFrequency` for a schedule.
@@ -108,6 +99,15 @@ While these properties are marked as optional, a data publisher must provide eit
Defines the days of the month on which the Event takes place. Specified as an integer between 1 and 31 Example "byMonthDay": [
28
]
+
+ | repeatFrequency |
+
+ Duration
+ |
+
+ Defines the frequency at which Events will occur according to a Schedule. The intervals between events should be defined as a Duration of time. Example "repeatFrequency": "P1D"
+ |
+
@@ -228,6 +228,15 @@ While these properties are marked as optional, a data publisher must provide eit
Defines the number of times a recurring Event will take place. Example "repeatCount": 3
|
+
+ | repeatFrequency |
+
+ Duration
+ |
+
+ Defines the frequency at which Events will occur according to a Schedule. The intervals between events should be defined as a Duration of time. Example "repeatFrequency": "P1D"
+ |
+
diff --git a/docs/data-model/types/scheduledsession.md b/docs/data-model/types/scheduledsession.md
index 5ae4a10b..8b65af70 100644
--- a/docs/data-model/types/scheduledsession.md
+++ b/docs/data-model/types/scheduledsession.md
@@ -28,33 +28,6 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
Must always be present and set to "type": "ScheduledSession"
-
- | activity |
-
- Array of Concept
- |
-
- Specifies the physical activity or activities that will take place during an event. Example "activity": [
{
"type": "Concept",
"id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
"prefLabel": "Bodypump™",
"inScheme": "https://openactive.io/activity-list"
}
]
- |
-
-
- | location |
-
- Place
- |
-
- The location at which the event will take place. Or, in the case of events that may span multiple locations, the initial meeting or starting point. It is recommended that locations should be specified as a Place complete with a fully described geographic location and/or address.If only an address is available then this should be described as a PostalAddress. Applications may use schema:Text to provide a more general description of a location ("In Victoria Park, near the lake"), but this is not recommended: consuming applications will be unable to help users discover opportunities based on their location. Example "location": {
"address": {
"addressLocality": "New Malden",
"addressRegion": "London",
"postalCode": "NW5 3DU",
"streetAddress": "Raynes Park High School, 46A West Barnes Lane",
"type": "PostalAddress"
},
"description": "Raynes Park High School in London",
"geo": {
"latitude": 51.4034423828125,
"longitude": -0.2369088977575302,
"type": "GeoCoordinates"
},
"id": "https://example.com/locations/1234ABCD",
"identifier": "1234ABCD",
"name": "Raynes Park High School",
"telephone": "01253 473934",
"type": "Place"
}
- |
-
-
- | name |
-
- Text
- |
-
- The name of the event Example "name": "Speedball"
- |
-
| startDate |
@@ -112,7 +85,7 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
Array of Person
|
- Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
+ Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"gender": "https://schema.org/Male",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
|
@@ -193,6 +166,15 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
Used to specify the types of disabilities or impairments that are supported at an event.
Example
"accessibilitySupport": [
{
"type": "Concept",
"id": "https://openactive.io/accessibility-support#1393f2dc-3fcc-4be9-a99f-f1e51f5ad277",
"prefLabel": "Visual impairment",
"inScheme": "https://openactive.io/accessibility-support"
}
]
+
+ | activity |
+
+ Array of Concept
+ |
+
+ Specifies the physical activity or activities that will take place during an event. Example "activity": [
{
"type": "Concept",
"id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
"prefLabel": "Bodypump™",
"inScheme": "https://openactive.io/activity-list"
}
]
+ |
+
| ageRange |
@@ -301,6 +283,15 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
A general purpose property for specifying the suitability of an event for different participant “levels”. E.g. beginner/intermediate/advanced. Or in the case of martial arts, specific belt requirements. Example "level": [
"beginner"
]
|
+
+ | location |
+
+ Place
+ |
+
+ The location at which the event will take place. Or, in the case of events that may span multiple locations, the initial meeting or starting point. It is recommended that locations should be specified as a Place complete with a fully described geographic location and/or address.If only an address is available then this should be described as a PostalAddress. Applications may use schema:Text to provide a more general description of a location ("In Victoria Park, near the lake"), but this is not recommended: consuming applications will be unable to help users discover opportunities based on their location. Example "location": {
"address": {
"addressLocality": "New Malden",
"addressRegion": "London",
"postalCode": "NW5 3DU",
"streetAddress": "Raynes Park High School, 46A West Barnes Lane",
"type": "PostalAddress"
},
"description": "Raynes Park High School in London",
"geo": {
"latitude": 51.4034423828125,
"longitude": -0.2369088977575302,
"type": "GeoCoordinates"
},
"id": "https://example.com/locations/1234ABCD",
"identifier": "1234ABCD",
"name": "Raynes Park High School",
"telephone": "01253 473934",
"type": "Place"
}
+ |
+
| meetingPoint |
@@ -310,13 +301,22 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
Instructions for the attendees of an Event about where they should meet the organizer or leader at the start of the event. Some larger locations may have several possible meeting points, so this property provides additional more specific directions. Example "meetingPoint": "At the entrance to the park"
|
+
+ | name |
+
+ Text
+ |
+
+ The name of the event Example "name": "Speedball"
+ |
+
| organizer |
Organization
- or -
Person
|
- The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": [
{
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
]
+ The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
@@ -349,7 +349,7 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
| superEvent |
- Event
+ Event
- or -
url
|
Relates a child event to a parent event. Properties describing the parent event can be assumed to apply to the child, unless otherwise specified. A parent event might specify a recurring schedule, of which the child event is one specific instance
diff --git a/docs/data-model/types/sessionseries.md b/docs/data-model/types/sessionseries.md
index 4c4e26c0..ea90b5d3 100644
--- a/docs/data-model/types/sessionseries.md
+++ b/docs/data-model/types/sessionseries.md
@@ -55,13 +55,22 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
The name of the event Example "name": "Speedball"
|
+
+ | offers |
+
+ Array of Offer
+ |
+
+ An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
+ |
+
| organizer |
Organization
- or -
Person
|
- The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": [
{
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
]
+ The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person. Example "organizer": {
"name": "Central Speedball Association",
"type": "Organization",
"url": "http://www.speedball-world.com"
}
|
@@ -139,7 +148,7 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
Array of Person
- Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
+ Refers to a person (schema:Person) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor. The person will need to have given their consent for their personal information to be present in the Open Data. Example "leader": [
{
"type": "Person",
"familyName": "Smith",
"givenName": "Nicole",
"gender": "https://schema.org/Male",
"id": "https://example.com/locations/1234ABCD/leaders/89",
"identifier": 89
}
]
|
@@ -151,15 +160,6 @@ This type is derived from [https://schema.org/Event](https://schema.org/Event),
A general purpose property for specifying the suitability of an event for different participant “levels”. E.g. beginner/intermediate/advanced. Or in the case of martial arts, specific belt requirements.
Example
"level": [
"beginner"
]
-
- | offers |
-
- Array of Offer
- |
-
- An array of schema:Offer that include the price of attending. Example "offers": [
{
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 3.3,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
]
- |
-
diff --git a/docs/data-model/types/slot.md b/docs/data-model/types/slot.md
index 34880694..1e0e4c96 100644
--- a/docs/data-model/types/slot.md
+++ b/docs/data-model/types/slot.md
@@ -46,6 +46,15 @@ description: This page describes the Slot type.
URI to the FacilityUse that has this offer
Example
"facilityUse": "https://example.com/facility-use/1"
+
+ | offers |
+
+ Array of Offer
+ |
+
+ An array of schema:Offer that include the price of booking. Example "offers": {
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 7.5,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
+ |
+
| remainingUses |
@@ -165,15 +174,6 @@ While these properties are marked as optional/recommended in the Modelling Speci
A local non-URI identifier for the resource Example "identifier": "SB1234"
|
-
- | offers |
-
- Array of Offer
- |
-
- An array of schema:Offer that include the price of booking. Example "offers": {
"type": "Offer",
"identifier": "OX-AD",
"name": "Adult",
"price": 7.5,
"priceCurrency": "GBP",
"url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
}
- |
-
diff --git a/docs/using-data/harvesting-opportunity-data.md b/docs/using-data/harvesting-opportunity-data.md
index 21fb0adf..64654e32 100644
--- a/docs/using-data/harvesting-opportunity-data.md
+++ b/docs/using-data/harvesting-opportunity-data.md
@@ -1,6 +1,6 @@
# Harvesting opportunity data
-## **Introduction** {#introduction}
+## **Introduction**
To follow along you’ll need some existing knowledge of programming, including familiarity with HTTP, JSON, and APIs.
@@ -15,13 +15,13 @@ By the end of this tutorial you’ll have:
Whilst you’ll be able to follow along with this tutorial as your sole guide, you may wish to refer to the OpenActive [Realtime Paged Data Exchange](https://www.openactive.io/realtime-paged-data-exchange/) specification for greater detail at points.
-## **Before we begin** {#before-we-begin}
+## **Before we begin**
Before we dive into implementation, let’s start with a bit of background. [OpenActive](https://www.openactive.io/) intends to facilitate the sharing and use of physical activity opportunity data. To date, a number of datasets have been made available for use. You can find out more about them in our upcoming guide ‘How to find physical activity opportunity data using the OpenActive Opportunity Data Dashboard’, or through the [status dashboard](https://status.openactive.io/) itself.
This is a tutorial which aims to cover how to harvest the data from these feeds. For simplicity, we’re going to focus on harvesting data from a single source, however at the end of this tutorial we’ll include some prompters for how to approach combining data from multiple sources.
-## **Data transport** {#data-transport}
+## **Data transport**
First of all, it’s important to understand the general approach to how the data is transported.
@@ -39,11 +39,11 @@ The RPDE specification recommends use of standard HTTP status codes. So your cod
To harvest all of the data from a feed your code will need to make repeated HTTP requests until it has fetched all the data. There’s no need for any authentication as all of the endpoints are freely available.Now that we understand the mechanic for transferring data, let’s move on to understanding the content of what’s returned from a request, and how we navigate through all of the content.
-## **Understanding paging** {#understanding-paging}
+## **Understanding paging**
Before we grab the data there are a few key concepts that are important to understand.
-### **Data is returned as pages** {#data-is-returned-as-pages}
+### **Data is returned as pages**
Looking at the [URL we previously visited](https://opensessions.io/api/Session/GetSessionsForOpenActive), you’ll notice that the data isn’t extensive - there are only 10 items in the items array.
@@ -57,7 +57,7 @@ From the link we opened \(and the image above\), you’ll notice the property ne
Follow the links a couple of times to get a feel for this, but there’s no need to go to the end \(we’ll come on to that shortly\).
-### **How items appear in the overall list \(and pages\)** {#how-items-appear-in-the-overall-list-and-pages}
+### **How items appear in the overall list \(and pages\)**
If you’ve looked into some of the items that have been returned, you may notice that some opportunities are in the past. The next important point to understand here is that the specification requires strict chronological ordering of items, with newly added and modified data added to the end of the feed. There are some simple rules that govern items in the overall list:
@@ -72,11 +72,11 @@ A conceptual view of a first page of items, followed by the rest of the list. No
Let’s move on to putting this into practice, to understand it in context.
-## **Doing our initial download** {#doing-our-initial-download}
+## **Doing our initial download**
When consuming the data for the first time, pages are initially downloaded sequentially to catch up with the current state of the data publisher. As we’ve seen, this is achieved by following the next property of each page until the last page is reached.
-### **The last page** {#the-last-page}
+### **The last page**
According to the spec definition, the last page of data must have both of the following properties:
@@ -128,7 +128,7 @@ In pseudocode, a very basic \(and unrobust\) page through the dataset for the fi
At this point, what you have is an as-is store of all of the items in the dataset, from as far back as they are available. Whilst this tutorial has not covered any processing of the data, so you will need to be mindful of getting it into a sensible state for your needs.
-## **Deleted items** {#deleted-items}
+## **Deleted items**
Whilst we’ve captured all of the items, what we also haven’t done is given any consideration to their state.
@@ -184,9 +184,9 @@ For our initial download of data, for now \(we’ll revisit this in the next sec
Our initial import of data should therefore now reflect only the current, active records. However, as we’ve seen, records can be amended and deleted.
-## **Keeping data up to date** {#keeping-data-up-to-date}
+## **Keeping data up to date**
-### **Handling updates and deletions** {#handling-updates-and-deletions}
+### **Handling updates and deletions**
Even with a small initial import, we run the risk of an item that we harvest early on actually being updated or deleted in the publisher’s system at the same time. As we’ve seen, this will lead to that item moving through the queue and being added to the end, so it could show up one to many times before our overall harvest is finished.
@@ -247,7 +247,7 @@ Our pseudocode therefore becomes a little bit more detailed:
-### **Polling for near real-time updates** {#polling-for-near-real-time-updates}
+### **Polling for near real-time updates**
Whilst we’ve reached the end of the feed, handled modifications and deletions, the changes don’t stop there. In order to keep your data updated in near real-time, you may wish to keep track of the URL for the last page, and infrequently poll this to check for updates. Revisiting the rules of what defines a page as the last page:
@@ -336,7 +336,7 @@ If items are found, your harvester should resume the behaviour of the initial do
-## **Extending this example: harvesting from multiple sources** {#extending-this-example-harvesting-from-multiple-sources}
+## **Extending this example: harvesting from multiple sources**
As mentioned at the start of this tutorial, once you’ve mastered harvesting from a single source you may well wish to extend this by harvesting multiple sources.
@@ -346,7 +346,7 @@ Whilst this is beyond the scope of this tutorial, we’ve included some pointers
* Whether or not you wish to re-harvest the full set of data every time.
* Whether or not you plan to harvest datasets sequentially, or in parallel.
-## **Resources** {#resources}
+## **Resources**
The specification that covers the Realtime Pages Data Exchange format in more detail can be found here: [https://www.openactive.io/realtime-paged-data-exchange/](https://www.openactive.io/realtime-paged-data-exchange/)
diff --git a/docs/using-data/how-to-find-opportunity-data-using-the-openactive-opportunity-data-dashboard.md b/docs/using-data/how-to-find-opportunity-data-using-the-openactive-opportunity-data-dashboard.md
new file mode 100644
index 00000000..92995f5d
--- /dev/null
+++ b/docs/using-data/how-to-find-opportunity-data-using-the-openactive-opportunity-data-dashboard.md
@@ -0,0 +1,70 @@
+# How to find opportunity data using the OpenActive Opportunity Data Dashboard
+
+## **Introduction**
+
+If you’re looking to use physical activity opportunity data within your website or app, you’re probably wanting to understand what’s available to you, and to identify which of it will help you meet your goals. To support people with this we’ve created the OpenActive Opportunity Data Dashboard.
+
+The status dashboard can be found at [status.openactive.io](http://status.openactive.io/). It lists all of the openly licensed datasets and APIs published as part of the OpenActive initiative, as well as highlighting attributes of each set.
+
+In this guide we’ll cover:
+
+* Seeing what data is available
+* How you can find data that meets your needs
+* Taking your next steps
+
+## **How to see all of the open opportunity data that’s available**
+
+When landing on [status.openactive.io](http://status.openactive.io/), you’re presented with a table that contains an overview of each dataset currently available under the OpenActive initiative. Each row on the table represents a different dataset. These are ordered alphabetically by default, but you can sort the table in different ways to help you explore.
+
+
+
+As part of [the publishing process](https://www.openactive.io/getting-started/) for datasets, we ask publishers to provide some basic information about their feeds, including where the endpoint is located. Because of this, feeds will automatically appear on the dashboard when they’re reviewed and published.
+
+The list of datasets on the dashboard and the summaries are regularly updated. The date and time of the last update is displayed on the main page and the individual dataset summary pages
+
+You can keep up to date with new datasets by checking the site periodically, by signing up to the [mailing list](https://us13.list-manage.com/subscribe?u=9e6648557f84731796a4ac873&id=1665f95799), or at the bottom of the page there is an option to ‘[Download JSON list](http://status.openactive.io/datasets.json)’. This links to a file containing a snapshot of all of the information on the status site, including the sampled output. You can use this machine-readable version to automatically integrate new datasets into your application.
+****
+
+
+
+
+
+## **How to find information that meets your needs**
+
+Whilst some people may wish to harvest all of the data available, others will be focused on certain types of data - perhaps certain activities or geographies - and may wish to understand more about the content of the datasets. The status site lets you do this in a few different ways. Looking at each row in the table, you may want to consider some or all of the following:
+
+### Key dataset information
+
+* Provider - includes the name of the organisation publishing the data. This links through to more information, optionally including mailing list, documentation, and more.
+* Endpoint - includes an indicator of whether the API is currently up or down. This links through to the URL for the dataset/API.
+
+**Conformance to standards, and known issues**
+
+* Uses paging spec - with a link to the specification itself in the header of the table, this column represents whether or not the dataset conforms to the standards around how data is transferred for harvesting. For each feed, clicking on the entry will take you to the validator tool which will tell you of the errors conforming to v1.1 of the RPDE spec.
+* Uses opportunity model - similarly, the opportunity model specification is linked in the table header. This column represents whether or not the dataset conforms to standards around the model of the data itself. For each feed, clicking on the entry will take you to the validator tool which will tell you of any errors conforming to v2 of the data model spec.
+* Issues - showing the number of open issues and discussions relating to this dataset. This links through to the dataset’s GitHub issue tracker.
+
+### **Activity types and geography**
+
+* Summary - if a dataset conforms to the standard data model then the dashboard will automatically generate a summary page for it. These pages are based on a daily sample of data from the data feed and provide an overview of the most common activities present in the dataset, as well as a summaryof their geographical spread across local authority areas. Please note that as the counts are from a sample, they are not reflective of the total number of opportunities.
+* Includes coordinates - a recommendation of the standards is that opportunity data should include geographic coordinates for locations, to better support geographical searching. Where there is any evidence of coordinates, this flag is set to yes.
+
+
+
+### **How the data can be used**
+
+* Licence - this indicates which open data licence the publisher has chosen to apply to their dataset. OpenActive recommends the Creative Commons Attribution licence which means you can use the data for any purpose, so long as you attribute your sources.
+
+## **How to use the data that you’ve found**
+
+Once you’ve identified and made of note of the datasets that meet your needs, you’ll then need to harvest the data for each using their endpoints \(linked through in the endpoint column, or found using the data-url attribute in the JSON file\).
+
+How to do this is covered in another tutorial, which you can find [here](harvesting-opportunity-data.md).
+
+## **What if there is other data you want?**
+
+**I**f there’s data missing from providers with an open feed \(e.g. they’ve only published kids activities and you want to use adult activities, or they haven’t provided detailed enough descriptions\) let them know through their GitHub repository, linked through their line on the status page. You can also let us know at [hello@openactive.io](mailto:hello@openactive.io) or on [Slack ](https://www.openactive.io/public-openactive-w3c/)as we can help coordinate you with other data users.
+
+If you’re looking for data from a provider who isn’t yet open, let us know at [hello@openactive.io](mailto:hello@openactive.io). We can let you know where that organisation is at in their open data journey, link you up to other data users so you can coordinate efforts, and support you to work directly with the data provider to get the data you want.
+
+