openactive 0.1.0.rc1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93c227814f9139f11ffc43555c7d667fdc100e04110de9d70612811c6fb22aaa
-  data.tar.gz: 2ec12d6038256e74a7f01ba2ac38139fec37dd0dd0d61bdaa72b5b191eb1dd8a
+  metadata.gz: c88ea62add4f15cd402a29d350d7186717da3c8c0b7feb3eb080f08156c0a792
+  data.tar.gz: 0b72d6feb18932a711e2a390038aac95c6e0e028bd0b68efe61162b94d5a7939
 SHA512:
-  metadata.gz: e8ed3a7f93fca01494ed42d8e9acfe256a6297f9e273f42b5bcd7bfd1fcafeeeb4820248104fbfeecb68f0ea59413360d19e88404ceadb94dd4f94c1e19146e0
-  data.tar.gz: c48c618544c7be88f31adec42443ab9067acd440842bc07b0b045b875a7184b32d34a016d26a5ce0ebca40aea9159091b846d556cf59c457f4e4bd4332c16992
+  metadata.gz: b60135e0c0aa90f25f80a90219a3690fc6899886f638f0940e14a3d44d1c9f1a2204a5f654b119c9164878ed016054398690587f3232978ef49ae45db9748998
+  data.tar.gz: 2151a398e7907a1a7f8395c547f7d2acad88c888753c121bef946306afb0052eee52c32e8e2ff909a1c33cc61d95f35c507504fd6c0798d67870c60014901fd5

data/README.md

@@ -22,8 +22,146 @@ 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.
+
+## 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.

data/lib/openactive/base_model.rb

@@ -35,7 +35,7 @@ module OpenActive
 
       val = value
 
-      val = deserialize_value(value) if value.is_a?(Array) || value.is_a?(Hash)
+      val = deserialize(value) if value.is_a?(Array) || value.is_a?(Hash)
 
       return if ["context", "type"].include?(attr_name)
 
@@ -49,10 +49,7 @@ module OpenActive
     # @param data [string,Array] If a string is provided, we attempt JSON-decoding first
     # @return [object]
     #
-    def self.deserialize(data)
-      # If a string is provided, we attempt JSON-decoding first
-      data = JSON.parse(data) if data.is_a?(String)
-
+    def self.deserialize_class(data)
       inst = new
 
       # If data provided is not an array, return an empty class
@@ -65,15 +62,11 @@ module OpenActive
       inst
     end
 
-    def deserialize(*data)
-      self.class.deserialize(data)
-    end
-
     # Returns a value from a given JSON-LD deserialized array.
     #
     # @param value [mixed] If an array is provided, we recursively deserialize it
     # @return [mixed]
-    def deserialize_value(value)
+    def self.deserialize(value)
       if value.is_a?(Hash)
         # If an associative array with a type, return its deserialization form,
         # so that it gets converted from array to object
@@ -87,7 +80,7 @@ module OpenActive
 
           klass = ::OpenActive::Models.const_get(type)
 
-          inst = klass.deserialize(value)
+          inst = klass.deserialize_class(value)
 
           return inst
         end
@@ -96,12 +89,16 @@ module OpenActive
         # If providing a non-associative array
         # Loop through it and serialize each item if needed
         value = value.map do |item|
-          deserialize_value(item)
+          deserialize(item)
         end
       end
       value
     end
 
+    def deserialize(*data)
+      self.class.deserialize(*data)
+    end
+
     # Returns the JSON-LD representation of the given instance.
     #
     # @param obj [::OpenActive::BaseModel] The given instance to convert to JSON-LD

data/lib/openactive/version.rb

@@ -1,3 +1,3 @@
 module OpenActive
-  VERSION = "0.1.0.rc1".freeze
+  VERSION = "0.1.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openactive
 version: !ruby/object:Gem::Version
-  version: 0.1.0.rc1
+  version: 0.1.0
 platform: ruby
 authors:
 - OpenActive Community
@@ -1022,11 +1022,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: OpenActive.io objects turned into strongly typed classes for use in Ruby.