lutaml-hal 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5a918f01a4197929abfdbbdd1e061ecff5d37592ed0c880024ec11f6abe2943
-  data.tar.gz: 032f6ba78ced7adefc4b6a9ce9c2c76acc25eba6b9d3d96398f3f09d330d312b
+  metadata.gz: b1006ba9c57ff945fa51c368b1ca12971d83fc47f668513a962da76811b6cc91
+  data.tar.gz: 4bc4bc6697181d9512604736ba42a6d4ce16d67d235ffd5ef79b481e09ca8243
 SHA512:
-  metadata.gz: '0802c9c05fbb34fc5a8d53a023cdd1cfda2291305b597387a5cc7afc665c9aa7eac542f03840cac494389c49442a030e79e7fdcf2169d992747e7a707fc4d9fa'
-  data.tar.gz: 7ecabcdc778455d9d4fee7b9708c7754891ab64e3da5edb6b88927cc687806b3c5863dde63b89aa785cdcf8174c431b58fa862e0a6443e456faad13fcced0faf
+  metadata.gz: befafec41b21cd9244ae937bdb5ce5e975a99bd708cd960e68b4db122554b73d73ef506bc82bda0961d196f10785957c10246d14607345d2e8239420571b1a58
+  data.tar.gz: e719a907ff8e198f797691829b4fab1280e866f8a403ca80945a55f0178d48a0737c274dc12f3052c635d96f53d7ca3663081f12359293638aa7d6b2d45f9845

data/README.adoc

@@ -71,6 +71,10 @@ A registry for managing HAL resource models and their endpoints. It allows you
 to register models, define their relationships, and fetch resources from the
 API.
 
+`Lutaml::Hal::GlobalRegister`::
+A global registry (Singleton) for managing ModelRegisters and facilitating model
+resolution across different resources. Its usage is optional.
+
 `Lutaml::Hal::Resource`::
 A base class for defining HAL resource models. It includes methods for
 defining attributes, links, and key-value mappings for resources.
@@ -96,6 +100,8 @@ At the data definition phase:
 . Define the API endpoint using the `Client` class.
 . Create a `ModelRegister` to manage the resource models and their
 respective endpoints.
+. (optional) Create a `GlobalRegister` to manage one or more `ModelRegister`
+  instances. It is necessary for automatic Link resolution.
 . Define the resource models using the `Resource` class.
 . Register the models with the `ModelRegister` and define their
 relationships using the `add_endpoint` method.
@@ -145,10 +151,38 @@ require 'lutaml-hal'
 
 # Create a new client with API endpoint
 client = Lutaml::Hal::Client.new(api_url: 'https://api.example.com')
-register = Lutaml::Hal::ModelRegister.new(client: client)
+register = Lutaml::Hal::ModelRegister.new(name: :my_model_register, client: client)
 # Or set client later, `register.client = client`
 ----
 
+The `name:` parameter is used to identify the `ModelRegister` instance.
+
+=== Creating a HAL global register
+
+The `GlobalRegister` class is a singleton that manages one or more
+`ModelRegister` instances.
+
+It is optional, but is required for automatic realization of models from Link
+objects. See <<fetching_resource_via_link_realization>> for more details.
+
+[source,ruby]
+----
+require 'lutaml-hal'
+
+# Create a new client with API endpoint
+client = Lutaml::Hal::Client.new(api_url: 'https://api.example.com')
+register = Lutaml::Hal::ModelRegister.new(name: :my_model_register, client: client)
+
+# Register the ModelRegister with the global register
+global_register = Lutaml::Hal::GlobalRegister.instance.register(:my_model_register, register)
+
+# Obtain the global register
+global_register.get(:my_model_register)
+
+# Delete a register mapping
+global_register.delete(:my_model_register)
+----
+
 
 === Defining HAL resource models
 
@@ -158,7 +192,7 @@ A HAL resource is defined by creating a subclass of the `Resource` class and
 defining its attributes, links, and key-value mappings.
 
 The `Resource` class is the base class for defining HAL resource models.
-It inherits from `Lutaml::Model::Serialization`, which provides data
+It inherits from `Lutaml::Model::Serializable`, which provides data
 modelling and serialization capabilities.
 
 The declaration of attributes, links, and key-value mappings for a HAL resource
@@ -580,6 +614,69 @@ register.add_endpoint(
 ====
 
 
+[[defining_hal_page_models]]
+=== Defining HAL page models
+
+HAL index APIs often support pagination, which allows clients to retrieve a
+limited number of resources at a time.
+
+The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs. It is a
+subclass of `Resource`, and provides additional attributes and methods for
+handling pagination information
+
+The `Page` class by default supports the following attributes:
+
+`page`:: The current page number.
+`pages`:: The total number of pages.
+`limit`:: The number of resources per page.
+`total`:: The total number of resources.
+
+The way to use the `Page` class is through inheritance from it, where the
+class will automatically create the necessary links for typical page objects.
+
+The typical links of a page object are:
+
+`self`:: A link to the current page.
+`prev`:: A link to the previous page.
+`next`:: A link to the next page.
+`first`:: A link to the first page.
+`last`:: A link to the last page.
+
+The "realize class" of these links are the same as the inherited page
+object, ensuring consistency in the pagination model.
+
+Syntax:
+
+[source,ruby]
+----
+class ProductIndex < Lutaml::Hal::Page
+  # No attributes necessary
+end
+
+register.add_endpoint(
+  id: :product_index,
+  type: :index,
+  url: '/products',
+  model: ProductIndex
+)
+
+page_1 = register.fetch(:product_index)  # Updated to use the correct endpoint id
+page_2_link = page_1.links.next
+# => <#ProductIndexLink href: "/products/2", title: "Next Page">
+----
+
+Where,
+
+`ProductIndex`:: The class of the page that will be fetched from the API. The class
+must inherit from `Lutaml::Hal::Page`.
+`register`:: The instance of `ModelRegister`.
+`id`:: The ID of the pagination endpoint to be registered in the `ModelRegister`.
+`url`:: The URL of the pagination endpoint.
+`model`:: The class of the page that will be fetched from the API.
+
+
+
+
 == Usage: Runtime
 
 === General
@@ -668,9 +765,6 @@ them using the `fetch` method.
 The `fetch` method will automatically handle the URL resolution and fetch the
 resource index from the API.
 
-// The `Page` class is used to handle pagination and resource
-// resolution for collections.
-
 Syntax:
 
 [source,ruby]
@@ -720,16 +814,34 @@ product_index
 ====
 
 
+[[fetching_resource_via_link_realization]]
 === Fetching a resource via link realization
 
 Given a resource index that contains links to resources, the individual resource
 links can be "realized" as actual model instances through the
-`Link#realize(register)` method which dynamically retrieves the resource.
+`Link#realize(register:)` method which dynamically retrieves the resource.
 
 Given a `Link` object, the `realize` method fetches the resource from the API
 using the provided `register`.
 
-Syntax:
+There are two ways a resource gets realized from a `Link` object:
+
+* If a `Lutaml::Hal::GlobalRegister` is used, and the `Link` object originated
+from a fetch using a `ModelRegister` then the `realize` method has sufficient
+information to automatically fetch the resource from the API using the same
+`register`.
++
+NOTE: This relies on the `Hal::REGISTER_ID_ATTR_NAME` attribute to be set
+in the `ModelRegister` class. This attribute is used to identify the
+resource endpoint ID in the URL.
+
+* If a `GlobalRegister` is not used, even if the Link object originated
+from a fetch using a `ModelRegister`, the `realize` method does not have sufficient
+information to fetch the resource from the API using the same
+`register`. In this case an explicit `register` must be provided to the
+`realize(register: ...)` method.
+
+Syntax for standalone usage:
 
 [source,ruby]
 ----
@@ -753,12 +865,26 @@ NOTE: It is possible to use the `realize` method on a link object using another
 `ModelRegister` instance. This is useful when you want to resolve a link
 using a different API endpoint or a different set of resource models.
 
+Syntax when using a `GlobalRegister`:
+
+[source,ruby]
+----
+resource_index = model_register.fetch(:resource_index)
+resource_index.links.products.first.realize
+# => client.get('/resources/1')
+----
+
 .Dynamically realizing a resource from the collection using links
 [example]
 ====
 [source,ruby]
 ----
+# Without a GlobalRegister
 product_2 = product_index.links.products.last.realize(register)
+
+# With a GlobalRegister
+product_2 = product_index.links.products.last.realize
+
 # => client.get('/products/2')
 # => {
 #   "id": 2,
@@ -782,54 +908,23 @@ product_2
 #                         <ProductLink href: "/products/4", title: "Product 4">,
 #                         <ProductLink href: "/products/6", title: "Product 6">
 #                     ]}>
-----
-====
-
-=== Pagination
-
-HAL index APIs often support pagination, which allows clients to retrieve a
-limited number of resources at a time.
 
-The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs. The
-`Page` class itself is implemented as a `Resource`, so you can use the same
-methods to access the page's attributes and links.
+# Without a GlobalRegister
+product_2_related_1 = product_2.links.related.first.realize(register)
 
-The `Page` class by default supports the following attributes:
-
-`page`:: The current page number.
-`pages`:: The total number of pages.
-`limit`:: The number of resources per page.
-`total`:: The total number of resources.
-
-Syntax:
-
-[source,ruby]
+# With a GlobalRegister
+product_2_related_1 = product_2.links.related.first.realize
 ----
-class MyPage < Lutaml::Hal::Page
-  # These are typical links given for page objects
-  hal_link :self, key: 'self', realize_class: 'MyPage'
-  hal_link :prev, key: 'prev', realize_class: 'MyPage'
-  hal_link :next, key: 'next', realize_class: 'MyPage'
-  hal_link :first, key: 'first', realize_class: 'MyPage'
-  hal_link :last, key: 'last', realize_class: 'MyPage'
-end
+====
 
-register.add_endpoint(
-  id: :my_pages,
-  type: :index,
-  url: '/my_pages',
-  model: MyPage
-)
-----
 
-Where,
+=== Handling HAL pages / pagination
 
-`MyPage`:: The class of the page that will be fetched from the API. The class
-must inherit from `Lutaml::Hal::Page`.
-`register`:: The instance of `ModelRegister`.
-`id`:: The ID of the pagination endpoint to be registered in the `ModelRegister`.
-`url`:: The URL of the pagination endpoint.
-`model`:: The class of the page that will be fetched from the API.
+The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs.
+
+As described in <<defining_hal_page_models>>, subclassing the `Page` class
+provides pagination capabilities, including the management of links to navigate
+through pages of resources.
 
 
 .Usage example of the Page class
@@ -839,19 +934,15 @@ Declaration:
 
 [source,ruby]
 ----
-class MyPage < Lutaml::Hal::Page
-  hal_link :self, key: 'self', realize_class: 'MyPage'
-  hal_link :prev, key: 'prev', realize_class: 'MyPage'
-  hal_link :next, key: 'next', realize_class: 'MyPage'
-  hal_link :first, key: 'first', realize_class: 'MyPage'
-  hal_link :last, key: 'last', realize_class: 'MyPage'
+class ResourceIndex < Lutaml::Hal::Page
+  # No attribute definition necessary
 end
 
 register.add_endpoint(
-  id: :my_pages,
+  id: :resource_index,
   type: :index,
-  url: '/my_pages',
-  model: MyPage
+  url: '/resources',
+  model: ResourceIndex
 )
 ----
 
@@ -859,32 +950,51 @@ Usage:
 
 [source,ruby]
 ----
-page_1 = register.fetch(:my_pages)
-# => client.get('/my_pages')
+page_1 = register.fetch(:resource_index)
+# => client.get('/resources')
 # => {
 #   "page": 1,
 #   "pages": 10,
 #   "limit": 10,
 #   "total": 100,
 #   "_links": {
-#     "self": { "href": "/my_pages" },
-#     "next": { "href": "/my_pages/2" },
-#     "last": { "href": "/my_pages/9" }
+#     "self": {
+#       "href": "https://api.example.com/resources?page=1&items=10"
+#     },
+#     "first": {
+#       "href": "https://api.example.com/resources?page=1&items=10"
+#     },
+#     "last": {
+#       "href": "https://api.example.com/resources?page=10&items=10"
+#     },
+#     "next": {
+#       "href": "https://api.example.com/resources?page=2&items=10"
+#     }
 #   }
 # }
+
 page_1
-# => #<MyPage page: 1, pages: 10, limit: 10, total: 100,
-#      links: #<MyPageLinks self: <MyPageLink href: "/my_pages">,
-#                     next: <MyPageLink href: "/my_pages/2">,
-#                     last: <MyPageLink href: "/my_pages/9">>>
+# => #<ResourceIndex page: 1, pages: 10, limit: 10, total: 100,
+#      links: #<ResourceIndexLinks
+#                self: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                next: #<ResourceIndexLink href: "/resources?page=2&items=10">,
+#                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>
+
+# Without a GlobalRegister
 page_2 = page.links.next.realize(register)
-# => client.get('/my_pages/2')
-# => #<MyPage page: 2, pages: 10, limit: 10, total: 100,
-#      links: #<MyPageLinks self: <MyPageLink href: "/my_pages/2">,
-#                     prev: <MyPageLink href: "/my_pages/1">,
-#                     next: <MyPageLink href: "/my_pages/3">,
-#                     first: <MyPageLink href: "/my_pages/1">,
-#                     last: <MyPageLink href: "/my_pages/9">>>
+
+# With a GlobalRegister
+page_2 = page.links.next.realize
+
+# => client.get('/resources?page=2&items=10')
+# => #<ResourceIndex page: 2, pages: 10, limit: 10, total: 100,
+#      links: #<ResourceIndexLinks
+#                self: #<ResourceIndexLink href: "/resources?page=2&items=10">,
+#                prev: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                next: #<ResourceIndexLink href: "/resources?page=3&items=10">,
+#                first: #<ResourceIndexLink href: "/resources?page=1&items=10">,
+#                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>,
+#                prev: #<ResourceIndexLink href: "/resources?page=1&items=10">>>
 ----
 ====
 

data/lib/lutaml/hal/client.rb

@@ -19,12 +19,19 @@ module Lutaml
         @debug = options[:debug] || !ENV['DEBUG_API'].nil?
         @cache = options[:cache] || {}
         @cache_enabled = options[:cache_enabled] || false
+
+        @api_url = strip_api_url(@api_url)
+      end
+
+      # Strip any trailing slash from the API URL
+      def strip_api_url(url)
+        url.sub(%r{/\Z}, '')
       end
 
       # Get a resource by its full URL
       def get_by_url(url, params = {})
         # Strip API endpoint if it's included
-        path = url.sub(%r{^#{@api_url}/}, '')
+        path = strip_api_url(url)
         get(path, params)
       end
 
@@ -62,7 +69,7 @@ module Lutaml
       end
 
       def handle_response(response, url)
-        debug_log(response, url) if @debug
+        debug_api_log(response, url) if @debug
 
         case response.status
         when 200..299
@@ -80,11 +87,11 @@ module Lutaml
         end
       end
 
-      def debug_log(response, url)
+      def debug_api_log(response, url)
         if defined?(Rainbow)
-          puts Rainbow("\n===== DEBUG: HAL API REQUEST =====").blue
+          puts Rainbow("\n===== Lutaml::Hal DEBUG: HAL API REQUEST =====").blue
         else
-          puts "\n===== DEBUG: HAL API REQUEST ====="
+          puts "\n===== Lutaml::Hal DEBUG: HAL API REQUEST ====="
         end
 
         puts "URL: #{url}"

data/lib/lutaml/hal/errors.rb

@@ -8,5 +8,6 @@ module Lutaml
     class BadRequestError < Error; end
     class ServerError < Error; end
     class LinkResolutionError < Error; end
+    class ParsingError < Error; end
   end
 end

data/lib/lutaml/hal/global_register.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Lutaml
+  module Hal
+    # Global register for model registers
+    # This class is a singleton that manages the registration and retrieval of model registers.
+    # It ensures that each model register is unique and provides a way to access them globally.
+    #
+    # @example
+    #   global_register = GlobalRegister.instance
+    #   global_register.register(:example, ExampleModelRegister.new)
+    #   example_register = global_register.get(:example)
+    class GlobalRegister
+      include Singleton
+
+      def initialize
+        @model_registers = {}
+      end
+
+      def register(name, model_register)
+        if @model_registers[name] && @model_registers[name] != model_register
+          raise "Model register with name #{name} replacing another one" \
+                " (#{@model_registers[name].inspect} vs #{model_register.inspect})"
+        end
+
+        @model_registers[name] = model_register
+      end
+
+      def get(name)
+        raise "Model register with name #{name} not found" unless @model_registers[name]
+
+        @model_registers[name]
+      end
+
+      def delete(name)
+        return unless @model_registers[name]
+
+        @model_registers.delete(name)
+      end
+    end
+  end
+end

data/lib/lutaml/hal/link.rb

@@ -7,6 +7,10 @@ module Lutaml
   module Hal
     # HAL Link representation with realization capability
     class Link < Lutaml::Model::Serializable
+      # This is the model register that has fetched the origin of this link, and
+      # will be used to resolve unless overriden in resource#realize()
+      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+
       attribute :href, :string
       attribute :title, :string
       attribute :name, :string
@@ -16,9 +20,33 @@ module Lutaml
       attribute :profile, :string
       attribute :lang, :string
 
-      # Fetch the actual resource this link points to
-      def realize(register)
-        register.resolve_and_cast(href)
+      # Fetch the actual resource this link points to.
+      # This method will use the global register according to the source of the Link object.
+      # If the Link does not have a register, a register needs to be provided explicitly
+      # via the `register:` parameter.
+      def realize(register: nil)
+        register = find_register(register)
+        raise "No register provided for link resolution (class: #{self.class}, href: #{href})" if register.nil?
+
+        Hal.debug_log "Resolving link href: #{href} using register"
+        register.resolve_and_cast(self, href)
+      end
+
+      private
+
+      def find_register(explicit_register)
+        return explicit_register if explicit_register
+
+        register_id = instance_variable_get("@#{Hal::REGISTER_ID_ATTR_NAME}")
+        return nil if register_id.nil?
+
+        register = Lutaml::Hal::GlobalRegister.instance.get(register_id)
+        if register.nil?
+          raise 'GlobalRegister in use but unable to find the register. '\
+            'Please provide a register to the `#realize` method to resolve the link'
+        end
+
+        register
       end
     end
   end

data/lib/lutaml/hal/link_set.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'model_register'
+
+module Lutaml
+  module Hal
+    # HAL Link representation with realization capability
+    class LinkSet < Lutaml::Model::Serializable
+      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+    end
+  end
+end

data/lib/lutaml/hal/model_register.rb

@@ -6,9 +6,10 @@ module Lutaml
   module Hal
     # Register to map URL patterns to model classes
     class ModelRegister
-      attr_accessor :models, :client
+      attr_accessor :models, :client, :register_name
 
-      def initialize(client: nil)
+      def initialize(name:, client: nil)
+        @register_name = name
         # If `client` is not set, it can be set later
         @client = client
         @models = {}
@@ -39,27 +40,59 @@ module Lutaml
         url = interpolate_url(endpoint[:url], params)
         response = client.get(url)
 
-        endpoint[:model].from_json(response.to_json)
+        realized_model = endpoint[:model].from_json(response.to_json)
+
+        mark_model_links_with_register(realized_model)
+        realized_model
       end
 
-      def resolve_and_cast(href)
+      def resolve_and_cast(link, href)
         raise 'Client not configured' unless client
 
-        debug_log("href #{href}")
+        Hal.debug_log("resolve_and_cast: link #{link}, href #{href}")
         response = client.get_by_url(href)
 
-        # TODO: Merge more content into the resource
+        # TODO: Merge full Link content into the resource?
         response_with_link_details = response.to_h.merge({ 'href' => href })
 
         href_path = href.sub(client.api_url, '')
+
         model_class = find_matching_model_class(href_path)
         raise LinkResolutionError, "Unregistered URL pattern: #{href}" unless model_class
 
-        debug_log("model_class #{model_class}")
-        debug_log("response: #{response.inspect}")
-        debug_log("amended: #{response_with_link_details}")
+        Hal.debug_log("resolve_and_cast: resolved to model_class #{model_class}")
+        Hal.debug_log("resolve_and_cast: response: #{response.inspect}")
+        Hal.debug_log("resolve_and_cast: amended: #{response_with_link_details}")
 
-        model_class.from_json(response_with_link_details.to_json)
+        model = model_class.from_json(response_with_link_details.to_json)
+        mark_model_links_with_register(model)
+        model
+      end
+
+      # Recursively mark all models in the link with the register name
+      # This is used to ensure that all links in the model are registered
+      # with the same register name for consistent resolution
+      def mark_model_links_with_register(inspecting_model)
+        return unless inspecting_model.is_a?(Lutaml::Model::Serializable)
+
+        inspecting_model.instance_variable_set("@#{Hal::REGISTER_ID_ATTR_NAME}", @register_name)
+
+        # Recursively process model attributes to mark links with this register
+        inspecting_model.class.attributes.each_pair do |key, config|
+          attr_type = config.type
+          next unless attr_type < Lutaml::Hal::Resource ||
+                      attr_type < Lutaml::Hal::Link ||
+                      attr_type < Lutaml::Hal::LinkSet
+
+          value = inspecting_model.send(key)
+          next if value.nil?
+
+          # Handle both array and single values with the same logic
+          values = value.is_a?(Array) ? value : [value]
+          values.each { |item| mark_model_links_with_register(item) }
+        end
+
+        inspecting_model
       end
 
       private
@@ -103,11 +136,15 @@ module Lutaml
         pattern_with_wildcards = pattern.gsub(/\{[^}]+\}/, '*')
         # Convert * wildcards to regex pattern
         regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '[^/]+')}$")
-        regex.match?(url)
-      end
 
-      def debug_log(message)
-        puts "DEBUG: #{message}" if ENV['DEBUG_API']
+        Hal.debug_log("pattern_match?: regex: #{regex.inspect}")
+        Hal.debug_log("pattern_match?: href to match #{url}")
+        Hal.debug_log("pattern_match?: pattern to match #{pattern_with_wildcards}")
+
+        matches = regex.match?(url)
+        Hal.debug_log("pattern_match?: matches = #{matches}")
+
+        matches
       end
     end
   end

data/lib/lutaml/hal/page.rb

@@ -19,6 +19,19 @@ module Lutaml
         map 'pages', to: :pages
         map 'total', to: :total
       end
+
+      def self.inherited(subclass)
+        super
+
+        page_links_symbols = %i[self next prev first last up]
+        subclass_name = subclass.name
+        subclass.class_eval do
+          # Define common page links
+          page_links_symbols.each do |link_symbol|
+            hal_link link_symbol, key: link_symbol.to_s, realize_class: subclass_name
+          end
+        end
+      end
     end
   end
 end

data/lib/lutaml/hal/resource.rb

@@ -7,6 +7,10 @@ module Lutaml
   module Hal
     # Resource class for all HAL resources
     class Resource < Lutaml::Model::Serializable
+      # This is the model register that has fetched this resource, and
+      # will be used to resolve links unless overriden in resource#realize()
+      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+
       class << self
         attr_accessor :link_definitions
 
@@ -35,20 +39,22 @@ module Lutaml
           # Use the provided "key" as the attribute name
           attribute_name = attr_key.to_sym
 
+          Hal.debug_log "Defining HAL link for `#{attr_key}` with realize class `#{realize_class}`"
+
           # Create a dynamic Link subclass name based on "realize_class", the
           # class to realize for a Link object, if `link_class:` is not provided.
           link_klass = link_class || create_link_class(realize_class)
 
           # Create a dynamic LinkSet class if `link_set_class:` is not provided.
           unless link_set_class
-            link_set_klass = link_set_class || get_links_class
+            link_set_klass = link_set_class || get_link_set_class
             link_set_klass.class_eval do
               # Declare the corresponding lutaml-model attribute
               attribute attribute_name, link_klass, collection: collection
 
               # Define the mapping for the attribute
               key_value do
-                map attr_key, to: attribute_name
+                map key, to: attribute_name
               end
             end
           end
@@ -67,10 +73,10 @@ module Lutaml
         end
 
         # This method obtains the Links class that holds the Link classes
-        def get_links_class
+        def get_link_set_class
           parent_klass_name = name.split('::')[0..-2].join('::')
           child_klass_name = "#{name.split('::').last}LinkSet"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
 
           raise unless Object.const_defined?(klass_name)
 
@@ -84,17 +90,18 @@ module Lutaml
         def create_link_set_class
           parent_klass_name = name.split('::')[0..-2].join('::')
           child_klass_name = "#{name.split('::').last}LinkSet"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
+
+          Hal.debug_log "Creating link set class #{klass_name}"
 
           # Check if the LinkSet class is already defined, return if so
           return Object.const_get(klass_name) if Object.const_defined?(klass_name)
 
           # Define the LinkSet class dynamically as a normal Lutaml::Model class
-          # since it is not a Resource
-          klass = Class.new(Lutaml::Model::Serializable)
-          Object.const_get(parent_klass_name).tap do |parent_klass|
-            parent_klass.const_set(child_klass_name, klass)
-          end
+          # since it is not a Resource.
+          klass = Class.new(Lutaml::Hal::LinkSet)
+          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
+          parent_klass.const_set(child_klass_name, klass)
 
           # Define the LinkSet class with mapping inside the current class
           class_eval do
@@ -112,8 +119,10 @@ module Lutaml
         # This is a Link class that helps us realize the targeted class
         def create_link_class(realize_class_name)
           parent_klass_name = name.split('::')[0..-2].join('::')
-          child_klass_name = "#{name.split('::').last}Link"
-          klass_name = "#{parent_klass_name}::#{child_klass_name}"
+          child_klass_name = "#{realize_class_name.split('::').last}Link"
+          klass_name = [parent_klass_name, child_klass_name].join('::')
+
+          Hal.debug_log "Creating link class #{klass_name} for #{realize_class_name}"
 
           return Object.const_get(klass_name) if Object.const_defined?(klass_name)
 
@@ -122,9 +131,9 @@ module Lutaml
             # Define the link class with the specified key and class
             attribute :type, :string, default: realize_class_name
           end
-          Object.const_get(parent_klass_name).tap do |parent_klass|
-            parent_klass.const_set(child_klass_name, klass)
-          end
+
+          parent_klass = !parent_klass_name.empty? ? Object.const_get(parent_klass_name) : Object
+          parent_klass.const_set(child_klass_name, klass)
 
           klass
         end

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.2'
+    VERSION = '0.1.4'
   end
 end

data/lib/lutaml/hal.rb

@@ -5,13 +5,20 @@ require 'lutaml/model'
 module Lutaml
   # HAL implementation for Lutaml
   module Hal
+    REGISTER_ID_ATTR_NAME = '_global_register_id'
+
+    def self.debug_log(message)
+      puts "[Lutaml::Hal] DEBUG: #{message}" if ENV['DEBUG_API']
+    end
   end
 end
 
 require_relative 'hal/version'
 require_relative 'hal/errors'
 require_relative 'hal/link'
+require_relative 'hal/link_set'
 require_relative 'hal/resource'
 require_relative 'hal/page'
+require_relative 'hal/global_register'
 require_relative 'hal/model_register'
 require_relative 'hal/client'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Ribose Inc.
@@ -80,7 +80,9 @@ files:
 - lib/lutaml/hal.rb
 - lib/lutaml/hal/client.rb
 - lib/lutaml/hal/errors.rb
+- lib/lutaml/hal/global_register.rb
 - lib/lutaml/hal/link.rb
+- lib/lutaml/hal/link_set.rb
 - lib/lutaml/hal/model_register.rb
 - lib/lutaml/hal/page.rb
 - lib/lutaml/hal/resource.rb