PR Comments

proto/cmp/services/insurance/v1alpha/insurance_types.proto

@@ -40,7 +40,7 @@ message InsurancePolicy {
 }
 
 message PolicyExtendedInfo {
-  // Policy with minimum info
+  // Insurance Policy dynamic info
   InsurancePolicy policy = 1;
 
   // Carrier code, not this provider is the holder of the policy and not a supplier to the Camino Network
@@ -49,7 +49,7 @@ message PolicyExtendedInfo {
   // Carrier name
   string carrier_name = 3;
 
-  // url to logo
+  // URL to logo
   cmp.types.v1.Image logo = 4;
 
   // enum of possible types, to be used for filtering
@@ -119,21 +119,21 @@ message PolicyCoverage {
   // Maximum coverage amount
   cmp.types.v1.Price max_coverage_amount = 3;
 
-  // url to Detailed list of risks covered
+  // URL to Detailed list of risks covered
   cmp.types.v1.Link coverage_link = 4;
 
-  // url to Specific events or conditions that are not covered by the policy
+  // URL to Specific events or conditions that are not covered by the policy
   cmp.types.v1.Link exclusions_link = 5;
 
   // pre-existing conditions coverage
   bool preconditions_coverage = 6;
 
-  // url to Details on whether pre-existing medical conditions are covered, and if so, under what terms.
+  // URL to Details on whether pre-existing medical conditions are covered, and if so, under what terms.
   cmp.types.v1.Link preconditions_coverage_link = 7;
 
-  // url to Full legal terms of the policy, privacy policy. compliance,..
+  // URL to Full legal terms of the policy, privacy policy. compliance,..
   cmp.types.v1.Link terms = 8;
 
-  // url to Frequently asked questions about the policy page
+  // URL to Frequently asked questions about the policy page
   cmp.types.v1.Link faq = 9;
 }

proto/cmp/services/insurance/v1alpha/search.proto

@@ -1,15 +1,22 @@
 syntax = "proto3";
 
-// ## Insurance Services
+// ## InsuranceServices
 //
-// The Insurance services are used for both hotels and holiday homes, often
-// called short term rentals.
+// Insurance Services has two main processes:
 //
-// Any search message response in the Camino Messenger Protocol only includes
-// dynamic data. Static data can be cached and kept up to data with the Product List
-// and Product Details messages.
+// - selling insurances: this process follows the same flow as selling any travel
+// product on the Camino Network: Static data download using the InsuranceProductList
+// message to obtain the (changed) portfolio of product a supplier offers, followed by
+// the InsuranceProductInfo message to get the exact detail of each product. The real-time data
+// does not contain any static information and consists of the InsuranceSearch message, followed
+// by the generic Validate and Mint messages.
 //
-// This package is a **WIP**.
+// - making an insurance claim: this is a special workflow, only used in the Insurance Services.
+// A claim form is requested based on the insurance policy purchased. This "template" is then
+// filled with the required information, the necessary documents are attached, and the claim is
+// submitted to the supplier. The supplier pushes a status upon change to the distributor.
+// It might be possible that further information is required or that an off-line conversation is taking place.
+// This finally leads to an acceptance and pay-out or a denial.
 package cmp.services.insurance.v1alpha;
 
 import "cmp/services/insurance/v1alpha/search_query_types.proto";
@@ -18,9 +25,19 @@ import "cmp/types/v1/common.proto";
 import "cmp/types/v1/search.proto";
 import "cmp/types/v1/traveller.proto";
 
-// The `Insurance Search Request` message type facilitates the request for
-// insurances. TODO: more description here ?!
+// InsuranceSearchRequest
 //
+// The Insurance Search Request message type facilitates the request for insurances
+// like health or cancellation insurances within the platform. In the request the market,
+// language and currency are specified at the top-level.
+//
+// In "queries" we specify the details of the insurances we would like to be offered.
+// In the Response, each InsuranceSearchResult is one bookable option as a "result_id".
+// Each consists of a "product" which indicates a type of insurance and if more options of
+// one type are available, then different units are offered. In case of an additional service,
+// like a sports package in combination with a health insurance, you would find one search result
+// with just the health insurance and another search result with both the health insurance and
+// the sports package.
 message InsuranceSearchRequest {
   // Message header. Contains API version, message info string and end-user wallet
   // address

proto/cmp/services/insurance/v1alpha/search_parameters_types.proto

@@ -17,7 +17,7 @@ import "cmp/types/v2alpha/product_code.proto";
 message InsuranceSearchParameters {
   // Product code list
   // Here a list of property codes would be used that could be of different types
-  repeated cmp.types.v2alpha.ProductCode product_codes = 1; // TODO: No supplier codes ?!!
+  repeated cmp.types.v2alpha.ProductCode product_codes = 1;
 
   // value of booking to be insured, only valid with CFAR, Flight? and Rantal Car? insurances
   double amount_purchase = 2;

proto/cmp/types/v2alpha/loyalty_program.proto

@@ -9,7 +9,8 @@ import "cmp/types/v1/link.proto";
 // ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v2alpha/loyalty_program.proto.dot.xs.svg)
 // [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v2alpha/loyalty_program.proto.dot.svg)
 message LoyaltyProgram {
-  // Smart contract address of a loyalty program if on-chain. In case of an off-chain loyalty program an ID in a loyalty system
+  // Smart contract address of a loyalty program if on-chain.
+  // In case of an off-chain loyalty program, this is the id of the loyalty program in loyalty system
   string id = 1;
 
   // Official name of the loyalty program that might be required to map