openactive 0.1.0.rc1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93c227814f9139f11ffc43555c7d667fdc100e04110de9d70612811c6fb22aaa
-  data.tar.gz: 2ec12d6038256e74a7f01ba2ac38139fec37dd0dd0d61bdaa72b5b191eb1dd8a
+  metadata.gz: 9076771a65bdda192786b2aa623817ac2c185f4786215d30c074859b0badff4e
+  data.tar.gz: e91eb80e55b80defc16dcae51a74f42388cfad79cf4452d5619508012a45c6e4
 SHA512:
-  metadata.gz: e8ed3a7f93fca01494ed42d8e9acfe256a6297f9e273f42b5bcd7bfd1fcafeeeb4820248104fbfeecb68f0ea59413360d19e88404ceadb94dd4f94c1e19146e0
-  data.tar.gz: c48c618544c7be88f31adec42443ab9067acd440842bc07b0b045b875a7184b32d34a016d26a5ce0ebca40aea9159091b846d556cf59c457f4e4bd4332c16992
+  metadata.gz: da906871a5055f4e34d957866a6ce9afe1abdaa1c44dad3f584a5422f4c2cfc092496bc469b5d7c103583a7c5b396f5b4b78283b1f31649840f52d0bc80b42c7
+  data.tar.gz: 48dd6d4fc20c5c34ba504e13211e6c6fee0eb2d4d2e3e29703602f02256ad803e1e1225ce6437e50ba49fe52d3fe1507e3de307b077e68e15021f3f05aa5dc48

data/.github/workflows/create-data-model-pr.yaml

@@ -0,0 +1,82 @@
+name: Update Data Model
+
+on:
+  workflow_dispatch:
+  repository_dispatch:
+    types: [data-models-update]
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout models-ruby
+        uses: actions/checkout@v2
+        with:
+          ref: master
+          path: models-ruby
+
+      - name: Checkout models-lib
+        uses: actions/checkout@v2
+        with:
+          repository: openactive/models-lib
+          path: models-lib
+
+      - name: Setup Node.js 14.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+        
+      - name: Install models-lib
+        run: npm install
+        working-directory: ./models-lib/
+        
+      - name: Update models-lib with latest data-models
+        run: npm update @openactive/data-models
+        working-directory: ./models-lib/
+
+      - name: Remove existing model files
+        run: rm -rf lib/openactive/models lib/openactive/enums
+        working-directory: ./models-lib/
+
+      - name: Run Ruby models generator
+        run: npm start -- generate Ruby --destination ../models-ruby/lib/openactive/
+        working-directory: ./models-lib/
+        
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          working-directory: ./models-ruby/
+
+      - name: Fix syntax / linting
+        run: bundle exec rubocop -a lib/openactive/models lib/openactive/enums
+        working-directory: ./models-ruby/
+
+      - name: Create Pull Request
+        id: cpr
+        uses: peter-evans/create-pull-request@v3
+        with:
+          path: ./models-ruby/
+          token: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
+          commit-message: Update data models
+          committer: openactive-bot <openactive-bot@users.noreply.github.com>
+          author: openactive-bot <openactive-bot@users.noreply.github.com>
+          signoff: false
+          branch: ci/update-data-models
+          delete-branch: true
+          title: 'Update data models'
+          body: |
+            Update Ruby data models to the latest version based on the [OpenActive Vocabulary](https://openactive.io/ns/) (codified by the [Data Models](https://github.com/openactive/data-models)), [Test Interface](https://openactive.io/test-interface/) and [Beta Namespace](https://openactive.io/ns-beta/).
+          labels: |
+            automated pr
+          team-reviewers: |
+            owners
+            maintainers
+          draft: false
+
+      - name: Check outputs
+        run: |
+          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
+          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

data/.github/workflows/release.yaml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+      with:
+        token: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
+
+    - name: Identify
+      run: |
+        git config user.name OpenActive Bot
+        git config user.email hello@openactive.io
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.7
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+    - name: Run tests
+      run: bundle exec rspec
+
+    - name: Publish to RubyGems
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        bundle exec rake release
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_API_KEY}}"

data/.github/workflows/tests.yaml

@@ -0,0 +1,26 @@
+name: Tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+    - name: Run tests
+      run: bundle exec rspec

data/.gitignore

@@ -1,3 +1,5 @@
+/vendor
+
 ### Ruby template
 *.gem
 *.rbc
@@ -11,6 +13,7 @@
 /test/version_tmp/
 /tmp/
 Gemfile.lock
+.rspec_status
 
 # Used by dotenv library to load environment variables.
 # .env

data/.rubocop.yml

@@ -56,12 +56,12 @@ RSpec/NestedGroups:
 Style/AsciiComments:
   Enabled: false
 
-Naming/UncommunicativeMethodParamName:
+Naming/MethodParameterName:
   AllowedNames:
     - as
     - id
 
-Metrics/LineLength:
+Layout/LineLength:
   Enabled: true
   Max: 120
   Exclude:

data/README.md

@@ -1,9 +1,11 @@
-# openactive gem - Ruby implementation of OpenActive's data model
+# openactive gem - Ruby implementation of OpenActive's data model [![Tests](https://github.com/openactive/models-ruby/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/openactive/models-ruby/actions/workflows/tests.yaml)
 
 Ruby Models for the OpenActive Opportunity and Booking Specifications
 
 OpenActive aims to provide model files for all classes defined in its Opportunity and Booking specifications across the PHP, Ruby, and .NET languages. This repository is intended for the Ruby files; see also the [PHP](https://github.com/openactive/models-php) and [.NET](https://github.com/openactive/OpenActive.NET) implementations.
 
+Additional documentation can be found at https://www.rubydoc.info/gems/openactive/.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,8 +24,221 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+This package provides Ruby models for the OpenActive specifications.
+
+It also provide a set of models for the [schema.org](https://schema.org) specifications.
+
+Finally it provides a set of classes to handle OpenActive's [RPDE](https://developer.openactive.io/publishing-data/data-feeds/how-a-data-feed-works) data feeds.
+
+### Models
+OpenActive includes OpenActive.io objects as objects for use in Ruby. All classes can be serialized into JSON-LD, to provide easy conformance with the [Modelling Specification](https://www.openactive.io/modelling-opportunity-data/) and [Open Booking API Specification](https://www.openactive.io/open-booking-api/).
+
+
+Please note that type enforcement is in place for both class construction and attribute assignment, providing an invalid type will result in a OpenActive::Exception::InvalidArgumentException being thrown.
+
+### OpenActive
+Classes for all OpenActive classes are available in the `OpenActive::Models` and `OpenActive::Enums` namespaces, and can be easily serialized to JSON-LD, as follows. Enumerations are available as `enum`s for properties that require their use.
+
+```ruby
+event = OpenActive::Models::Event.new(
+    name: "Virtual BODYPUMP",
+    event_status: OpenActive::Enums::Schema::EventStatusType::EventScheduled
+)
+json_ld = event.to_json
+```
+
+Value of `jsonLd`:
+```JSON
+{
+  "@context": "https://openactive.io/",
+  "@type": "Event",
+  "name": "Virtual BODYPUMP",
+  "eventStatus": "https://schema.org/EventScheduled"
+}
+```
+
+### Schema
+The OpenActive data model builds on top of Schema.org, which means that you are free to use additional schema.org properties within OpenActive published data.
+
+To reflect this, OpenActive uses inheritance to build ontop of a copy of Schema.org, these are available within the OpenActive::Models::Schema and OpenActive::Enums::Schema namespaces. And so makes it easy to use additional properties from schema.org on any given type.
+
+### Full Models Example
+```ruby
+session_series = OpenActive::Models::SessionSeries.new(
+    name: "Virtual BODYPUMP",
+    description: "This is the virtual version of the original barbell class, which will help you get lean, toned and fit - fast",
+    start_date: "2017-04-24T19:30:00-08:00",
+    end_date: "2017-04-24T23:00:00-08:00",
+    location: OpenActive::Models::Place.new(
+        name: "Raynes Park High School, 46A West Barnes Lane",
+        geo: OpenActive::Models::GeoCoordinates.new(
+            latitude: 51.4034423828125,
+            longitude: -0.2369088977575302,
+        )
+    ),
+    activity: OpenActive::Models::Concept.new(
+        id: "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
+        pref_label: "Bodypump™",
+        in_scheme: "https://openactive.io/activity-list"
+    ),
+    organizer: OpenActive::Models::Organization.new(
+        name: "Central Speedball Association",
+        url: "http://www.speedball-world.com"
+    ),
+    offers: [OpenActive::Models::Offer.new(
+        identifier: "OX-AD",
+        name: "Adult",
+        price: 3.30,
+        price_currency: "GBP",
+        url: "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
+    )]
+)
+
+session_series.to_json
+```
+This results in
+
+```json
+{
+  "@context": ["https://openactive.io/", "https://openactive.io/ns-beta"],
+  "@type": "SessionSeries",
+  "description": "This is the virtual version of the original barbell class, which will help you get lean, toned and fit - fast",
+  "offers": [{
+    "@type": "Offer",
+    "name": "Adult",
+    "url": "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB",
+    "price": "3.33",
+    "priceCurrency": "GBP",
+    "identifier": "OX-AD"
+  }],
+  "startDate": "2017-04-24T19:30:00-08:00",
+  "endDate": "2017-04-24T23:00:00-08:00",
+  "location": {
+    "@type": "Place",
+    "name": "Raynes Park High School, 46A West Barnes Lane",
+    "geo": {
+      "@type": "GeoCoordinates",
+      "longitude": "-0.2369088977575302e0",
+      "latitude": "0.514034423828125e2"
+    }
+  },
+  "organizer": {
+    "@type": "Organization",
+    "name": "Central Speedball Association",
+    "url": "http://www.speedball-world.com"
+  },
+  "activity": {
+    "@type": "Concept",
+    "@id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
+    "inScheme": "https://openactive.io/activity-list",
+    "prefLabel": "Bodypump™"
+  },
+  "name": "Virtual BODYPUMP"
+}
+```
+
+## RPDE Feed Publishing 
+
+To publish an OpenActive data feed (see this [video explainer](https://developer.openactive.io/publishing-data/data-feeds/how-a-data-feed-works)), The OpenActive gem provides a drop-in solution to render the feed pages. This also includes validation for the underlying feed query.
+
+### Modified Timestamp and ID Ordering Strategy
+
+`OpenActive::Rpde::RpdeBody.create_from_modified_id(feedBaseUrl, afterTimestamp, afterId, items)`
+
+Creates a new RPDE Page based on the RPDE Items provided using the [Modified Timestamp and ID Ordering Strategy](https://www.w3.org/2017/08/realtime-paged-data-exchange/#modified-timestamp-and-id), given the `afterTimestamp` and `afterId` parameters of the current query. Also validates that the items are in the correct order, throwing a `SerializationException` if this is not the case.
+
+```ruby
+items = [
+    OpenActive::Rpde::RpdeItem.new(
+        Id: "1",
+        Modified: 3,
+        State: OpenActive::Rpde::RpdeState::Updated,
+        Kind: OpenActive::Rpde::RpdeKind::SessionSeries,
+        Data: @event
+    ),
+    OpenActive::Rpde::RpdeItem.new(
+        Id: "2",
+        Modified: 4,
+        State: OpenActive::Rpde::RpdeState::Deleted,
+        Kind: OpenActive::Rpde::RpdeKind::SessionSeries,
+        Data: nil
+    )
+]
+
+json_ld = OpenActive::Rpde::RpdeBody.new("https://www.example.com/feed", 1, "1", items).to_json
+```
+
+
+### Incrementing Unique Change Number Ordering Strategy
+
+`OpenActive::Rpde::RpdeBody.create_from_next_change_number(feedBaseUrl, afterChangeNumber, items)`
+
+Creates a new RPDE Page based on the RPDE Items provided using the [Incrementing Unique Change Number Ordering Strategy](https://www.w3.org/2017/08/realtime-paged-data-exchange/#incrementing-unique-change-number), given the `afterChangeNumber` parameter of the current query. Also validates that the items are in the correct order, throwing a `SerializationException` if this is not the case.
+
+```ruby
+items = [
+    OpenActive::Rpde::RpdeItem.new(
+        Id: "1",
+        Modified: 3,
+        State: OpenActive::Rpde::RpdeState::Updated,
+        Kind: OpenActive::Rpde::RpdeKind::SessionSeries,
+        Data: @event
+    ),
+    OpenActive::Rpde::RpdeItem.new(
+        Id: "2",
+        Modified: 4,
+        State: OpenActive::Rpde::RpdeState::Deleted,
+        Kind: OpenActive::Rpde::RpdeKind::SessionSeries,
+        Data: nil
+    )
+]
+
+json_ld = OpenActive::Rpde::RpdeBody.create_from_next_change_number("https://www.example.com/feed", 2, items).to_json
+```
+
+## Serialization
+
+### `obj.serialize`
+Returns the serialized object in hash form complying to json-ld structure (unlike .to_h this serializes everything all the way down.)
+```
+event.serialize
+```
+```
+{"@type"=>"Event", "name"=>"Virtual BODYPUMP", "eventStatus"=>"https://schema.org/EventScheduled", "@context"=>["https://openactive.io/", "https://openactive.io/ns-beta"]}
+```
+### `obj.to_json`
+Serializes down to a json-ld string.
+```ruby
+event.to_json
+```
+returns
+```ruby
+"{\"@type\":\"Event\",\"name\":\"Virtual BODYPUMP\",\"eventStatus\":\"https://schema.org/EventScheduled\",\"@context\":[\"https://openactive.io/\",\"https://openactive.io/ns-beta\"]}"
+```
+
+## Deserialization
+```ruby
+
+data = JSON.parse('{"@context": ["https:\/\/openactive.io\/","https:\/\/openactive.io\/ns-beta"],"type": "Action","name": "Book","target": {"type": "EntryPoint","encodingType": "application\/vnd.openactive.v1.0+json","httpMethod": "POST","type": "EntryPoint","url": "https:\/\/example.com\/orders"}}')
 
+deserialized = OpenActive::BaseModel.deserialize(data)
+
+pp deserialized
+```
+
+will result in
+```ruby
+#<OpenActive::Models::Action:0x00007ff6fd0966d0
+ @name="Book",
+ @target=
+  #<OpenActive::Models::EntryPoint:0x00007ff6fd095fa0
+   @encoding_type="application/vnd.openactive.v1.0+json",
+   @http_method="POST",
+   @url=#<URI::HTTPS https://example.com/orders>>>
+=> #<OpenActive::Models::Action:0x00007ff6fd0966d0
+ @name="Book",
+ @target=#<OpenActive::Models::EntryPoint:0x00007ff6fd095fa0 @encoding_type="application/vnd.openactive.v1.0+json", @http_method="POST", @url=#<URI::HTTPS https://example.com/orders>>>
+```
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -33,3 +248,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/openactive/models-ruby.
+
+### Updating models
+A guide is provided in [UPDATING.md](UPDATING.md)

data/UPDATING.md

@@ -0,0 +1,49 @@
+# Updating models
+
+A convenience script has been provided, `./update-models.sh`.
+
+The process that's been automated here is roughly as follows:
+
+```bash
+# install and get the generator into place
+git clone https://github.com/openactive/models-lib vendor/models-lib
+mkdir -p vendor/models-lib
+cd vendor/models-lib
+npm install
+
+# generate models
+npm run app-dev -- generate Ruby --destination ../../lib/openactive/
+
+cd ../..
+# fix syntax / linting
+rubocop exec rubocop -a lib/openactive/models lib/openactive/enums
+
+# run tests
+rubocop exec rubocop -a rspec
+
+# add the newly generated models
+git add lib/openactive/models lib/openactive/enums lib/openactive/files-index.json
+```
+
+The next step is to commit it.
+
+```bash
+git commit -m 'Model update'
+git push # push up new branch
+```
+
+## Releasing
+
+Bump the version number in lib/openactive/version.rb, commit this and tag the repository with the matching version number.
+
+```bash
+git tag v0.0.0 # tag the matching version number
+git push origin v0.0.0 # push up new tag
+```
+
+then it's a case of building and pushing the gem.
+```bash
+gem build openactive
+gem push openactive-0.0.0.gem # substitute version with the build ver
+
+```