From 3786cca64fbec973cb7da82234c948507c91db43 Mon Sep 17 00:00:00 2001
From: Wim Van de Meerssche <wim.vandemeerssche@intec.ugent.be>
Date: Tue, 1 Jul 2014 15:00:24 +0200
Subject: [PATCH] proposal to add RSpec version to Allocate

---
 call-allocate.adoc | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/call-allocate.adoc b/call-allocate.adoc
index 681b0ff..516b929 100644
--- a/call-allocate.adoc
+++ b/call-allocate.adoc
@@ -10,7 +10,8 @@ At some aggregates, experimenter tools may call Allocate multiple times, to add
 ----------------
 Allocate(string slice_urn,
          struct credentials[],
-         string.rspec rspec,
+         struct request_rspec,
+         struct manifest_rspec_version,
          struct options)
 ----------------
 
@@ -28,25 +29,43 @@ String content type::  URN
 
 The URN of the slice to which the resources specified in rspec will be allocated. For details on URN identifiers, see link:general.html[this document].
 
-==== Argument 2: +rspec+
+==== Argument 2: +credentials+
+
+The standard authorization argument. See <<CommonArgumentCredentials, the Credentials section>>.
+
+==== Argument 3: +request_rspec+
 
 ***********************************
 [horizontal]
 Supported by the server:: Mandatory
 Included by client:: Mandatory
-XML-RPC type::  +string+
-String content type::  <<StringRspecDataType, +string.rspec+>>
+XML-RPC type:: 
+[source]
+  {
+      "type" : <string: (case insensitive, matching '^[a-zA-Z0-9][a-zA-Z0-9-_\.:]*$')>,
+      "version" : <string: (case insensitive, matching '^[a-zA-Z0-9][a-zA-Z0-9-_\.:]*$')>,
+      "rspec" : <string.rspec rspec>
+  }
+
+"rspec" String content type::  <<StringRspecDataType, +string.rspec+>>
 ***********************************
 
-An RSpec containing the resources that the caller is requesting for allocation to the slice specified in slice_urn. These are expected to be consistent with the resources returned by a previous invocation of <<ListResources>>. If this RSpec is in a format not listed as supported by <<GetVersion>>, then the aggregate will return an error of +BADVERSION (4)+.
+A request RSpec containing the resources that the caller is requesting for allocation to the slice specified in +slice_urn+. 
+These are expected to be consistent with the resources returned by a previous invocation of <<ListResources>>. 
+
+The format of the request RSpec is specified in the "version" and "type" fields, the request RSpec itself is specified in "rspec".
+If this RSpec is in a format not listed as supported by <<GetVersion>>, then the aggregate will return an error of +BADVERSION (4)+.
 
 For more details on RSpecs and RSpec versions, see the type <<StringRspecDataType, +string.rspec+>> and the link:rspec.html[Rspec Document].
 
-==== Argument 3: +credentials+
+==== Argument 4: +manifest_rspec_version+
 
-The standard authorization argument. See <<CommonArgumentCredentials, the Credentials section>>.
+The version of (manifest) RSpec that the client would like to receive in the reply to this call.
+If this is not a format listed as supported by <<GetVersion>>, then the aggregate will return an error of +BADVERSION (4)+.
+
+See the <<CommonArgumentRspecVersion, +rspec_version+ argument>> for details.
 
-==== Argument 4:  +options+
+==== Argument 5:  +options+
 
 A struct containing optional arguments, indexed by name. See <<OptionsArgument,General Options Argument Section>>.