agreement-design-prototype 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b8b0ee3c86692db54196238eb53be579e4b3f8b2bc24dee7a6dc67ca89d7068
-  data.tar.gz: 511c0e41fd44633b68f48efc18cb00a29b7692db569eb3ef112adcb6b7392e87
+  metadata.gz: 4be9d81a5edecf06009e29793a626e699d48f3c12a2d60003c8b18c857b287af
+  data.tar.gz: 28b6ebb6911ee923b868a76236f3ae3fc5fd9299eba00b6d139c35b47e072849
 SHA512:
-  metadata.gz: 7b167ee34fc849c9d4e4470a93ef8b21283f50c8e2059a5e862e1b1239255122cf605eb397e59da8b308b14138237f632a591330b8f3c72cca570e6afa2de3f8
-  data.tar.gz: feeca74a1f808b7663062910a89719db1c551d9a57b100a4f9088219e17b3141bb6eb88a0c6952bb958c9d75a5371c36279a7edc0223596b16c6bfe37bcc33f9
+  metadata.gz: 67f906f47daded5e621a16ceda86a5a1218c87e4ebb808abb6a68e8c6d63cd54284717feff59e68072c12c9c448d612a2de8ad94af34ea48d6b3fe2b4cbee316
+  data.tar.gz: 3952efcaf70a5efaa8b6c1507d910ae4fad7812e99217ccc7d289295ac2d9a5b8899318003ff938ef918a93c8842917283bed46f3e7dd4d5c0f37456a0a199a6

data/README.md

@@ -15,3 +15,18 @@ This prototype
 - possibly produces data domain descriptions, e.g. Ruby-on-Rails schema records
 
 
+# Things to see
+
+the [agreements](agreements/) directory defines our [agreements metamodel](model/agreement.rb) and our 
+[reference agreements and catalogues](model/fm.rb) 
+(example for fm given)
+
+the build script generates [outputs](gen) including
+
+- [data files](gen/data) showing the agreements and catalogue entries
+   - for instance, can bulk load [jsonlines](gen/data/fm_catalogue.jsonlines) for FM catalogue into search cluster
+- a [picture](gen/images/metamodel.jpg) of the metamodel
+- documentation for the agreements and metamodel
+
+
+

data/agreement-design.gemspec

@@ -1,7 +1,8 @@
 # agreement-design.gemspec
+# TODO - split the gem for schema design from the one containing agreement models
 Gem::Specification.new do |spec|
   spec.name          = "agreement-design-prototype"
-  spec.version       = "0.0.3"
+  spec.version       = "0.0.4"
   spec.authors       = ["CCS"]
   spec.homepage      = 'https://github.com/Crown-Commercial-Service/cmp-design-prototype/agreement-design'
   spec.email         = ["rubygems@humphries.tech"]

data/build/build_models.rb

@@ -1,16 +1,31 @@
 require_relative "../src/diagram"
+require_relative "../src/doc"
+require_relative "../src/data"
 require_relative "../model/agreement"
+require_relative "../model/fm"
+require_relative '../model/geographic'
 
-path= File.join(File.dirname(__FILE__), '../', "gen")
+path = File.join(File.dirname(__FILE__), '../', "gen")
 
-# TODO: escape the path somehow so it works when called direct. Works ok from Rake
-diagram= Diagram.new( path, "data_model")
-diagram.describe  Category, Parties
+metamodels = [Agreements, Parties, Geographic, FM]
+models = [Agreements::FM_Agreements, FM::FM_Catalogue, Geographic::NUTS]
 
-doc= Doc.new( path, "metamodel")
-doc.document_metamodel  Category, Parties
+diagram = Diagram.new(path, "metamodel")
+diagram.describe *metamodels
 
-doc= Doc.new( path, "frameworks")
-require_relative '../model/fm'
-doc.document  Category::FM
+doc = Document.new(path, "metamodel")
+doc.document_metamodel *metamodels
 
+doc = Document.new(path, "data")
+doc.document *models
+
+data= DataFile.new( path, "data", fmt: :json)
+data.output *models
+data= DataFile.new( path, "data", fmt: :yaml)
+data.output *models
+
+data= DataFile.new( path, "fm_agreements", fmt: :jsonlines)
+data.output Agreements::FM_Agreements
+
+data= DataFile.new( path, "fm_catalogue", fmt: :jsonlines)
+data.output FM::FM_Catalogue

data/gen/data/data.json

@@ -0,0 +1 @@
+{"agreement":[{"kind":"Framework","id":"FM","fwk_number":"RM8330","version":"0.1.0","description":"This agreement is for the provision of Facilities Management","start_date":"2018-10-01"},{"kind":"Lot","id":"FM lot 1","name":"low-to-mid value Facilities Management Lot","part_of_id":"FM","min_value":0,"max_value":70000000,"version":"0.1.0","item_type":[{"id":"FM.1a-C.3","scheme_id":"CCS","unit":"Currency","code":"CCS-building-area-method","keyword":["cleaning","washing","janitor"]}]}],"fm_offering":[{"supplier_id":"XYZ corp","name":"XYZ's nifty school cleaning service","agreement_id":"FM","location_id":["UK"],"sector":["Education"],"sc_cleared":"TRUE","item":[{"type":"FM.1a-C.3","value":3000}]}],"areacode":[{"name":"UK","subcode":[{"name":"UKC","description":"North East","subcode":[{"name":"UKC1","description":"Tees Valley and County Durham"}]},{"name":"UKL","description":"London"}]}]}

data/gen/data/data.yaml

@@ -0,0 +1,46 @@
+---
+:agreement:
+- :kind: :Framework
+  :id: FM
+  :fwk_number: RM8330
+  :version: 0.1.0
+  :description: This agreement is for the provision of Facilities Management
+  :start_date: 2018-10-01
+- :kind: :Lot
+  :id: FM lot 1
+  :name: low-to-mid value Facilities Management Lot
+  :part_of_id: FM
+  :min_value: 0
+  :max_value: 70000000
+  :version: 0.1.0
+  :item_type:
+  - :id: FM.1a-C.3
+    :scheme_id: :CCS
+    :unit: :Currency
+    :code: CCS-building-area-method
+    :keyword:
+    - cleaning
+    - washing
+    - janitor
+:fm_offering:
+- :supplier_id: XYZ corp
+  :name: XYZ's nifty school cleaning service
+  :agreement_id: FM
+  :location_id:
+  - :UK
+  :sector:
+  - :Education
+  :sc_cleared: 'TRUE'
+  :item:
+  - :type: FM.1a-C.3
+    :value: 3000
+:areacode:
+- :name: :UK
+  :subcode:
+  - :name: :UKC
+    :description: North East
+    :subcode:
+    - :name: :UKC1
+      :description: Tees Valley and County Durham
+  - :name: :UKL
+    :description: London

data/gen/data/fm_agreements.jsonlines

@@ -0,0 +1,2 @@
+{"kind":"Framework","id":"FM","fwk_number":"RM8330","version":"0.1.0","description":"This agreement is for the provision of Facilities Management","start_date":"2018-10-01"}
+{"kind":"Lot","id":"FM lot 1","name":"low-to-mid value Facilities Management Lot","part_of_id":"FM","min_value":0,"max_value":70000000,"version":"0.1.0","item_type":[{"id":"FM.1a-C.3","scheme_id":"CCS","unit":"Currency","code":"CCS-building-area-method","keyword":["cleaning","washing","janitor"]}]}

data/gen/data/fm_catalogue.jsonlines

@@ -0,0 +1 @@
+{"supplier_id":"XYZ corp","name":"XYZ's nifty school cleaning service","agreement_id":"FM","location_id":["UK"],"sector":["Education"],"sc_cleared":"TRUE","item":[{"type":"FM.1a-C.3","value":3000}]}

data/gen/diagrams/metamodel.dot

@@ -0,0 +1,45 @@
+strict digraph {
+subgraph cluster_Agreements {
+node [shape=plaintext margin=0];
+label=Agreements;
+"ItemType" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>ItemType</TD></TH><TR><TD ALIGN="LEFT">-id</TD></TR><TR><TD ALIGN="LEFT">-scheme_id</TD></TR><TR><TD ALIGN="LEFT">-description</TD></TR><TR><TD ALIGN="LEFT">-keyword</TD></TR><TR><TD ALIGN="LEFT">-uri</TD></TR><TR><TD ALIGN="LEFT">-code</TD></TR><TR><TD ALIGN="LEFT">-unit</TD></TR></table>>];
+"Need" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Need</TD></TH><TR><TD ALIGN="LEFT">-buyer_id</TD></TR><TR><TD ALIGN="LEFT">-kind</TD></TR><TR><TD ALIGN="LEFT">-unit</TD></TR></table>>];
+"Agreement" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Agreement</TD></TH><TR><TD ALIGN="LEFT">-kind</TD></TR><TR><TD ALIGN="LEFT">-id</TD></TR><TR><TD ALIGN="LEFT">-name</TD></TR><TR><TD ALIGN="LEFT">-version</TD></TR><TR><TD ALIGN="LEFT">-start_date</TD></TR><TR><TD ALIGN="LEFT">-end_date</TD></TR><TR><TD ALIGN="LEFT">-description</TD></TR><TR><TD ALIGN="LEFT">-fwk_number</TD></TR><TR><TD ALIGN="LEFT">-sf_typ</TD></TR><TR><TD ALIGN="LEFT">-sf_is</TD></TR><TR><TD ALIGN="LEFT">-part_of_id</TD></TR><TR><TD ALIGN="LEFT">-conforms_to_id</TD></TR><TR><TD ALIGN="LEFT">-item_type</TD></TR><TR><TD ALIGN="LEFT">-min_value</TD></TR><TR><TD ALIGN="LEFT">-max_value</TD></TR></table>>];
+"Item" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Item</TD></TH><TR><TD ALIGN="LEFT">-type</TD></TR><TR><TD ALIGN="LEFT">-unit</TD></TR><TR><TD ALIGN="LEFT">-value</TD></TR></table>>];
+"Offering" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Offering</TD></TH><TR><TD ALIGN="LEFT">-agreement_id</TD></TR><TR><TD ALIGN="LEFT">-supplier_id</TD></TR><TR><TD ALIGN="LEFT">-offerType</TD></TR><TR><TD ALIGN="LEFT">-name</TD></TR><TR><TD ALIGN="LEFT">-description</TD></TR><TR><TD ALIGN="LEFT">-item</TD></TR><TR><TD ALIGN="LEFT">-location_id</TD></TR><TR><TD ALIGN="LEFT">-sector</TD></TR></table>>];
+"Catalogue" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Catalogue</TD></TH><TR><TD ALIGN="LEFT">-offers</TD></TR></table>>];
+"Involvement" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Involvement</TD></TH><TR><TD ALIGN="LEFT">-agreement_id</TD></TR><TR><TD ALIGN="LEFT">-party_id</TD></TR><TR><TD ALIGN="LEFT">-role</TD></TR></table>>];
+}
+subgraph cluster_Parties {
+node [shape=plaintext margin=0];
+label=Parties;
+"Party" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Party</TD></TH><TR><TD ALIGN="LEFT">-id</TD></TR><TR><TD ALIGN="LEFT">-supplier_registration_completed</TD></TR><TR><TD ALIGN="LEFT">-buyer_registration_completed</TD></TR></table>>];
+}
+subgraph cluster_Geographic {
+node [shape=plaintext margin=0];
+label=Geographic;
+"AreaCode" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>AreaCode</TD></TH><TR><TD ALIGN="LEFT">-name</TD></TR><TR><TD ALIGN="LEFT">-description</TD></TR><TR><TD ALIGN="LEFT">-subcode</TD></TR></table>>];
+}
+subgraph cluster_FM {
+node [shape=plaintext margin=0];
+label=FM;
+"FM_Offering" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>FM_Offering</TD></TH><TR><TD ALIGN="LEFT">-agreement_id</TD></TR><TR><TD ALIGN="LEFT">-supplier_id</TD></TR><TR><TD ALIGN="LEFT">-offerType</TD></TR><TR><TD ALIGN="LEFT">-name</TD></TR><TR><TD ALIGN="LEFT">-description</TD></TR><TR><TD ALIGN="LEFT">-item</TD></TR><TR><TD ALIGN="LEFT">-location_id</TD></TR><TR><TD ALIGN="LEFT">-sector</TD></TR><TR><TD ALIGN="LEFT">-sc_cleared</TD></TR></table>>];
+}
+"Agreement" -> "Agreement" [label="part_of_id" arrowhead = "open" arrowtail = "none" ];
+"Agreement" -> "Agreement" [label="conforms_to_id" arrowhead = "open" arrowtail = "none" ];
+"Agreement" -> "ItemType" [label="{contains} item_type" arrowhead = "none" arrowtail = "diamond" ];
+"Item" -> "ItemType" [label="type" arrowhead = "open" arrowtail = "none" ];
+"Offering" -> "Agreement" [label="agreement_id" arrowhead = "open" arrowtail = "none" ];
+"Offering" -> "Party" [label="supplier_id" arrowhead = "open" arrowtail = "none" ];
+"Offering" -> "Item" [label="{contains} item" arrowhead = "none" arrowtail = "diamond" ];
+"Offering" -> "AreaCode" [label="location_id" arrowhead = "open" arrowtail = "none" ];
+"Catalogue" -> "Offering" [label="{contains} offers" arrowhead = "none" arrowtail = "diamond" ];
+"Involvement" -> "Agreement" [label="agreement_id" arrowhead = "open" arrowtail = "none" ];
+"Involvement" -> "Party" [label="party_id" arrowhead = "open" arrowtail = "none" ];
+"AreaCode" -> "AreaCode" [label="{contains} subcode" arrowhead = "none" arrowtail = "diamond" ];
+"FM_Offering" -> "Offering" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+"FM_Offering" -> "Agreement" [label="agreement_id" arrowhead = "open" arrowtail = "none" ];
+"FM_Offering" -> "Party" [label="supplier_id" arrowhead = "open" arrowtail = "none" ];
+"FM_Offering" -> "Item" [label="{contains} item" arrowhead = "none" arrowtail = "diamond" ];
+"FM_Offering" -> "AreaCode" [label="location_id" arrowhead = "open" arrowtail = "none" ];
+}

data/gen/doc/data.md

@@ -0,0 +1,44 @@
+###  FM 
+   - kind Framework
+   - id FM
+   - fwk_number RM8330
+   - version 0.1.0
+   - description This agreement is for the provision of Facilities Management
+   - start_date 2018-10-01
+### low-to-mid value Facilities Management Lot FM lot 1 
+   - kind Lot
+   - id FM lot 1
+   - name low-to-mid value Facilities Management Lot
+   - part_of_id FM
+   - min_value 0
+   - max_value 70000000
+   - version 0.1.0
+#### item_type FM.1a-C.3 
+     - id FM.1a-C.3
+     - scheme_id CCS
+     - unit Currency
+     - code CCS-building-area-method
+     - keyword cleaning
+     - keyword washing
+     - keyword janitor
+### XYZ's nifty school cleaning service  
+   - supplier_id XYZ corp
+   - name XYZ's nifty school cleaning service
+   - agreement_id FM
+   - location_id UK
+   - sector Education
+   - sc_cleared TRUE
+#### item  
+     - type FM.1a-C.3
+     - value 3000
+### UK  
+   - name UK
+#### UKC  
+     - name UKC
+     - description North East
+##### UKC1  
+       - name UKC1
+       - description Tees Valley and County Durham
+#### UKL  
+     - name UKL
+     - description London

data/gen/doc/metamodel.md

@@ -1,98 +1,140 @@
- # Category
-## ItemParameter
-  Defines the meaning of Items in Catalogues
+# Data model: Agreements
+## ItemType
+  Defines the items that can be offered in any selected agreements
+Agreements hava a number of items that can have values defining the agreement. The Items should
+constrain the key quantifiable elements of an agreement award. A supplier may provide additional
+variable facts in their Offer to supplement the description of how they support the agreement.
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1||
-|detail|String|1||
+|id|String|1|The code id, which must be unique across all schemes|
+|scheme_id|(CPV,CPVS,UNSPSC,CPV,OKDP,OKPD,CCS)|1|The classiciation scheme id|
+|description|String|1||
 |keyword|String|*||
-|valueMin|String|1||
-|valueMax|String|1||
-|type|String|1|One of: String, Currency, Location, Amount|
-|standard|String|1|which standard defines the item type, such as UBL2.1|
-|reference|String|1|reference within standard, such as UBL2.1|
-## Agreement
-  General definition of Commercial Agreements
+|uri|String|1| URI for the code within the scheme defining this type |
+|code|String|1| Code within the scheme defining this type |
+|unit|(Area,Currency)|1| define the units, if one units matches |
+## Need
+   Defines a buyer's need which can be matched to agreement items and other details
+The need matches closely to our definitions of agreements under 'items types' and their classification
+schemes, but is not a one-to-one match.
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1||
-|item_params|Category::ItemParameter|*||
-|version|String|1|semantic version id of the form X.Y.Z|
-|start_date|Date|1||
-|end_date|Date|1||
-## Framework extends Category::Agreement
-  A kind of Framework used for calloffs, composed of Lots
+|buyer_id|String|1|The buyer expressing the need|
+|kind|(Budget,Location,Service)|1||
+|unit|(Area,Currency)|1|The units typically used to express the need|
+## Agreement
+  General definition of Commercial Agreements
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1||
-|item_params|Category::ItemParameter|*||
+|kind|(Framework,Lot,Contract)|1|Kind of agreement, including :Framework, :Lot, :Contract|
+|id|String|1|uuid of agreeement|
+|name|String|1|uuid of agreeement|
 |version|String|1|semantic version id of the form X.Y.Z|
 |start_date|Date|1||
 |end_date|Date|1||
-|fwk_id|String|1|Such as the RM number|
-## Lot extends Category::Agreement
-  
+|description|String|1|Describe the agreement|
+|fwk_number|String|1|Framework (RM) number of related framework if required. @Example RM123|
+|sf_typ|String|1|SalesForce data type|
+|sf_is|String|1|SalesForce row id|
+|part_of_id|String -> Agreements::Agreement|1|Agreement this is part of, applicable only to Lots|
+|conforms_to_id|String -> Agreements::Agreement|1|Agreement this conforms to, such as a Contract conforming to a Framework|
+|item_type|Agreements::ItemType|*|describe the items that can be offered under the agreement|
+|min_value|Integer|0..1|Minimum value of award, in pounds sterling|
+|max_value|Integer|0..1|Maximum value of award, in pounds sterling|
+## Item
+  Specifies the value of an item that is being offered for an agreement
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1||
-|item_params|Category::ItemParameter|*||
-|version|String|1|semantic version id of the form X.Y.Z|
-|start_date|Date|1||
-|end_date|Date|1||
-|fwk_id|String|1|Part of framework|
-## Item
-  Something offered to a buyer as part of a contract.Items are defined in Catalogues.
+|type|String -> Agreements::ItemType|1| type of the item |
+|unit|(Area,Currency)|1| define the units |
+|value|Object|1|an object of the type matching type->units|
+## Offering
+   Supplier offering against an item or items of an agreement.
+This may be extended for different agreements. A supplier may provide additional
+variable facts in their Offer to supplement the description of how they support the agreement. 
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1|Item id, possibly a concatentation of the standard (in params) and the catalogue and an incrementatl id?|
-|params|String|1||
+|agreement_id|String -> Agreements::Agreement|1|The agreement this offering relates to|
+|supplier_id|String -> Parties::Party|1||
+|offerType|String|1|Name of the subclass of the Offering, supporting the Agreement|
+|name|String|1||
 |description|String|1||
-|value|String|1||
+|item|Agreements::Item|*|details of the item|
+|location_id|String -> Geographic::AreaCode|1..*|Pick list of applicable regions. There must be at least one, even if it is just 'UK'|
+|sector|(ALL,Education,CentralGov,WiderGov,Etc)|*|Pick list of applicable sectors.|
 ## Catalogue
-  A collection of items that can be bought via an Agreement.
+   A collection of supplier offerings against an item, for an agreement 
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1||
-|items|Category::Item|*||
-|agreement_id|String|1||
-## Offer
-  
+|offers|Agreements::Offering|*|description of the item|
+## Involvement
+  Involvement relationship between a party and an agreement
+Technology strategy documents call this type 'interest' but perhaps this could
+be confused with the accounting interest
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1|Offer id, probably a UUID|
-|item_id|String|1||
-|catalogue_id|String|1||
-|supplier_id|String|1||
-|description|String|1|Description of the offer|
-## Award
-  
+|agreement_id|String -> Agreements::Agreement|1|The agreement this interest relates to|
+|party_id|String -> Parties::Party|1|The party this interest relates to|
+|role|(AwardedSupplier,AwardedBuyer,SupplyingQuote,RequestingQuote,Etc)|1|The role of the party in the involvment|
+# Codes
+## CCS 
+CCS invented schemes
 
-|attribute|type|multiplicity|description|
-|---------|----|------------|-----------|
-|buyer_id|String|1||
- # Parties
+## Budget 
+What is the budget the buyer has for their need?
+Match the budget to the value range of the agreement, and the value range of supplier offers.
+Matching the budget will probably require evaluation of offer prices.
+
+## Location 
+Where is the need?
+Match location needs to locations of offers
+
+## Service 
+What sort of things do they need?
+Match the service to item types, their keywords, and offering titles.
+
+# Data model: Parties
 ## Party
   
+  The party is used to identify buyers and suppliers. Since some organisations act as
+both buyers and suppliers we use the same record for both, but most organisations will
+be one or the other. The onvolvement of the party with an agreement determine  the role in
+that contenxt.
+Details still to be added
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
 |id|String|1|UUID or Salesforce ID?|
-## Supplier extends Parties::Party
+|supplier_registration_completed|Date|1||
+|buyer_registration_completed|Date|1||
+# Data model: Geographic
+## AreaCode
   
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1|UUID or Salesforce ID?|
-## Buyer extends Parties::Party
-  
+|name|String|1||
+|description|String|1||
+|subcode|Geographic::AreaCode|*|UUID or Salesforce ID?|
+# Data model: FM
+## FM_Offering extends Agreements::Offering
+   An offer for FM elements 
 
 |attribute|type|multiplicity|description|
 |---------|----|------------|-----------|
-|id|String|1|UUID or Salesforce ID?|
+|agreement_id|String -> Agreements::Agreement|1|The agreement this offering relates to|
+|supplier_id|String -> Parties::Party|1||
+|offerType|String|1|Name of the subclass of the Offering, supporting the Agreement|
+|name|String|1||
+|description|String|1||
+|item|Agreements::Item|*|details of the item|
+|location_id|String -> Geographic::AreaCode|1..*|Pick list of applicable regions. There must be at least one, even if it is just 'UK'|
+|sector|(ALL,Education,CentralGov,WiderGov,Etc)|*|Pick list of applicable sectors.|
+|sc_cleared|String|1||

data/model/agreement.rb

@@ -1,69 +1,121 @@
 require_relative '../src/data_model'
 require_relative 'party'
-require 'date'
+require_relative 'geographic'
 include DataModel
 
-domain :Category do
+domain :Agreements do
 
-  datatype(:ItemParameter,
-           description: "Defines the meaning of Items in Catalogues") {
-    attribute :id, String
-    attribute :detail, String
+  SECTOR = Selection(:ALL, :Education, :CentralGov, :WiderGov, :Etc)
+  UNITS = Selection(:Area, :Currency)
+  CLASSIFICATION_SCHEMES = Selection(:CPV, :CPVS, :UNSPSC, :CPV, :OKDP, :OKPD, :CCS)
+  code(:CCS, description: "CCS invented schemes")
+
+  datatype(:ItemType,
+           description:
+"Defines the items that can be offered in any selected agreements
+Agreements hava a number of items that can have values defining the agreement. The Items should
+constrain the key quantifiable elements of an agreement award. A supplier may provide additional
+variable facts in their Offer to supplement the description of how they support the agreement.") {
+
+    attribute :id, String, "The code id, which must be unique across all schemes"
+    attribute :scheme_id, CLASSIFICATION_SCHEMES, "The classiciation scheme id"
+    attribute :description, String
     attribute :keyword, String, ZERO_TO_MANY
-    attribute :valueMin, String
-    attribute :valueMax, String
-    attribute :type, String, "One of: String, Currency, Location, Amount"
-    attribute :standard, String, "which standard defines the item type, such as UBL2.1"
-    attribute :reference, String, "reference within standard, such as UBL2.1"
+    attribute :uri, String, " URI for the code within the scheme defining this type "
+    attribute :code, String, " Code within the scheme defining this type "
+    attribute :unit, UNITS, " define the units, if one units matches "
+  }
+
+  CATEGORY_OF_NEED = Selection(:Budget, :Location, :Service)
+  code(:Budget, description:
+"What is the budget the buyer has for their need?
+Match the budget to the value range of the agreement, and the value range of supplier offers.
+Matching the budget will probably require evaluation of offer prices.")
+  code(:Location, description:
+"Where is the need?
+Match location needs to locations of offers")
+  code(:Service, description:
+"What sort of things do they need?
+Match the service to item types, their keywords, and offering titles.")
+
+  datatype(:Need,
+           description:
+" Defines a buyer's need which can be matched to agreement items and other details
+The need matches closely to our definitions of agreements under 'items types' and their classification
+schemes, but is not a one-to-one match.") {
+    attribute :buyer_id, String, "The buyer expressing the need"
+    attribute :kind, Selection(:Budget, :Location,)
+    attribute :kind, Selection(:Budget, :Location, :Service)
+    attribute :unit, UNITS, "The units typically used to express the need"
   }
 
   datatype(:Agreement,
            description: "General definition of Commercial Agreements") {
-    attribute :id, String
-    attribute :item_params, Category::ItemParameter, ZERO_TO_MANY, links: Category::ItemParameter
+
+    # identify the agreement
+    attribute :kind, Selection(:Framework, :Lot, :Contract),
+              #TODO doc should enumeration selections
+              "Kind of agreement, including :Framework, :Lot, :Contract"
+    attribute :id, String, "uuid of agreeement"
+    attribute :name, String, "uuid of agreeement"
     attribute :version, String, "semantic version id of the form X.Y.Z"
     attribute :start_date, Date
     attribute :end_date, Date
-  }
+    attribute :description, String, "Describe the agreement"
+    attribute :fwk_number, String, "Framework (RM) number of related framework if required. @Example RM123"
+    attribute :sf_typ, String, "SalesForce data type"
+    attribute :sf_is, String, "SalesForce row id"
 
-  datatype(:Framework, extends: Category::Agreement,
-           description: "A kind of Framework used for calloffs, composed of Lots") {
-    attribute :fwk_id, String, "Such as the RM number"
-  }
+    # structure of agreement
+    attribute :part_of_id, String, "Agreement this is part of, applicable only to Lots", links: :Agreement
+    attribute :conforms_to_id, String, "Agreement this conforms to, such as a Contract conforming to a Framework", links: :Agreement
+    attribute :item_type, :ItemType, ZERO_TO_MANY,
+              "describe the items that can be offered under the agreement"
+
+    # Qualifications
+    attribute :min_value, Integer, ZERO_OR_ONE, "Minimum value of award, in pounds sterling"
+    attribute :max_value, Integer, ZERO_OR_ONE, "Maximum value of award, in pounds sterling"
 
-  datatype(:Lot, extends: Category::Agreement) {
-    attribute :fwk_id, String, "Part of framework", links: Category::Framework
   }
 
   datatype(:Item,
-           description: "Something offered to a buyer as part of a contract."\
-                        "Items are defined in Catalogues.") {
-    attribute :id, String, "Item id, possibly a concatentation of the standard (in params) and the catalogue and an incrementatl id?"
-    attribute :params, String, links: Category::ItemParameter
-    attribute :description, String
-    attribute :value, String
+           description: "Specifies the value of an item that is being offered for an agreement") {
+    attribute :type, String, " type of the item ", links: :ItemType
+    attribute :unit, UNITS, " define the units "
+    attribute :value, Object, "an object of the type matching type->units"
   }
 
-  datatype(:Catalogue,
-           description: "A collection of items that can be bought via an Agreement.") {
-    attribute :id, String
-    attribute :items, Category::Item, ZERO_TO_MANY, links: Category::Item
-    attribute :agreement_id, String, links: Category::Agreement
+  datatype(:Offering,
+           description: " Supplier offering against an item or items of an agreement.
+This may be extended for different agreements. A supplier may provide additional
+variable facts in their Offer to supplement the description of how they support the agreement. ") {
+    attribute :agreement_id, String, "The agreement this offering relates to", links: :Agreement
+    attribute :supplier_id, String, links: Parties::Party
+    attribute :offerType, String, "Name of the subclass of the Offering, supporting the Agreement"
+    attribute :name, String
+    attribute :description, String
+    attribute :item, :Item, ZERO_TO_MANY, "details of the item"
+    # Qualifications
+    attribute :location_id, String, ONE_TO_MANY,
+              "Pick list of applicable regions. There must be at least one, even if it is just 'UK'",
+              links: Geographic::AreaCode
+    attribute :sector, SECTOR, ZERO_TO_MANY,
+              "Pick list of applicable sectors."
   }
 
-  datatype(:Offer,
-      description: "")  {
-    attribute :id, String, "Offer id, probably a UUID"
-    attribute :item_id, String, links: Category::Item
-    attribute :catalogue_id, String, links: Category::Catalogue
-    attribute :supplier_id, String, links: Parties::Supplier
-    attribute :description, String, "Description of the offer"
+  datatype(:Catalogue,
+           description: " A collection of supplier offerings against an item, for an agreement ") {
+    attribute :offers, :Offering, ZERO_TO_MANY, "description of the item"
   }
 
-  datatype(:Award,
-           description: "") {
-    attribute :buyer_id, String, links: Parties::Buyer
+  datatype(:Involvement,
+           description: "Involvement relationship between a party and an agreement
+Technology strategy documents call this type 'interest' but perhaps this could
+be confused with the accounting interest") {
+    attribute :agreement_id, String, "The agreement this interest relates to", links: :Agreement
+    attribute :party_id, String, "The party this interest relates to", links: Parties::Party
+    attribute :role, Selection(:AwardedSupplier, :AwardedBuyer, :SupplyingQuote, :RequestingQuote, :Etc),
+              "The role of the party in the involvment"
   }
 
-end
-
+end