Index: fedd/fedd_types.xsd
===================================================================
--- fedd/fedd_types.xsd	(revision 2c6128f4b78daa5149ee72a147011e123772d6b3)
+++ fedd/fedd_types.xsd	(revision 2dafa0c68ac0b0267acac2379c8ad3b7dd2a67d4)
@@ -8,5 +8,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	The types of user IDs
+	An ID is an identifier for a principal, service, or object.  This type
+	is currently polymorphic o allow different implementations of type,
+	though running code primarily uses localnames and fedids.
       </xsd:documentation>
     </xsd:annotation>
@@ -23,6 +25,10 @@
     <xsd:annotation>
       <xsd:documentation>
-	Nodes are described in terms of their images or hardware requirements.
-	This description may be empty
+	A node from an Emulab.  It may have 0 or more images or hardware
+	types associated with it.  As this description is used for
+	acquiring access to the testbed in question, multiple images or
+	types are considered options.  Specifying multiple image names
+	indicates that the requester is looking for support for any of
+	them.
       </xsd:documentation>
     </xsd:annotation>
@@ -37,4 +43,10 @@
 
   <xsd:simpleType name="kindType">
+    <xsd:annotation>
+      <xsd:documentation>
+	An indication of how requested networking capacity is measured.
+	This will undoubtably expand.
+      </xsd:documentation>
+    </xsd:annotation>
     <xsd:restriction base="xsd:string">
       <xsd:enumeration value="max"/>
@@ -46,5 +58,6 @@
     <xsd:annotation>
       <xsd:documentation>
-	Capacity value and type of cut
+	A strawman network capacity description for access negotiation.
+	This will come to include more and more interesting parameters.
       </xsd:documentation>
     </xsd:annotation>
@@ -58,5 +71,9 @@
     <xsd:annotation>
       <xsd:documentation>
-	The types of credentails used for remote project access
+	This captures an access credential that will be used to access
+	resources.  These are certificates or public keys.  The type is
+	used to designate the key to which access should be bound, or on
+	a reply has been bound.  Dynamic credentials where new keys have
+	been created may also be passed in this kind of field.
       </xsd:documentation>
     </xsd:annotation>
@@ -71,5 +88,10 @@
     <xsd:annotation>
       <xsd:documentation>
-	Purpose of this user - service access or experiment creation
+	This defines the role the user/account is playing in the
+	federated experiment.  An account being accessed by the
+	federation system to create the experiment is in the
+	experimentCreation role and the accounts that experimenters will
+	use to access local testbed services (e.g., rebooting a local
+	node) are serviceAccess roles.
       </xsd:documentation>
     </xsd:annotation>
@@ -84,6 +106,11 @@
     <xsd:annotation>
       <xsd:documentation>
-	A user consists of one or both of an identifier and an access
-	credential. 
+	The definition of a user principal.  It includes the
+	identification of the user as an ID type, the access credential(s)
+	that the user will use, and the role of the user, if any.
+	Multiple access keys may be used, and it is also possible for
+	the user to be anonymous.  Though it is possible to specify a
+	user without ID, access, or role, it is difficult to imagine
+	such a user being useful.
       </xsd:documentation>
     </xsd:annotation>
@@ -100,6 +127,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	A general attribute value pair for passing federation parameters and
-	preferences
+	A general attribute/value pair for passing federation parameters and
+	preferences.  Anything encodable in XML is allowed.  This is a
+	point for customization and extension.
       </xsd:documentation>
     </xsd:annotation>
@@ -114,5 +142,8 @@
     <xsd:annotation>
       <xsd:documentation>
-	An estimate of the resources than a federated experiment may require
+	The estimate of resources a requester is looking for, or the
+	response of a testbed indicating what it can provide.  This is
+	something of a placeholder for a full resource specification,
+	and alternative encodings are likely to be imported.
       </xsd:documentation>
     </xsd:annotation>
@@ -129,5 +160,11 @@
       <xsd:documentation>
 	Explicit translation of testbed attribute in a federated experiment
-	description.  Used in a creation request.
+	description to the URI at which the controlling federation
+	system can be reached.  Used in a creation request.
+
+	This type allows tools to encode experiments in familiar local
+	names for experimenters while providing remote federation
+	systems the information to map the local name into a service
+	location.
       </xsd:documentation>
     </xsd:annotation>
@@ -142,5 +179,8 @@
     <xsd:annotation>
       <xsd:documentation>
-	A project name and access user
+	A description of the project used to access a testbed.  Includes
+	the testbed being accessed, the project name (often a local
+	name, scoped by the testbed), and any users who have been
+	granted access or for whom access is being requested.
       </xsd:documentation>
     </xsd:annotation>
@@ -157,5 +197,9 @@
     <xsd:annotation>
       <xsd:documentation>
-	The information needed to swap an emulab experiment in
+	A description of an Emulab sufficient for the federation system
+	to create a sub experiment on it.  Note that fedAttrs provide an
+	extension mechanism by which testbeds may communicate additional
+	information and preferences to federation systems that
+	understand it.
       </xsd:documentation>
     </xsd:annotation>
@@ -175,5 +219,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	The information about a federated sub-experiment
+	Naming and Emulab instantiation information about a federant.
+	This is returned by various informational requests and as part
+	of a successful creation message.
       </xsd:documentation>
     </xsd:annotation>
@@ -190,5 +236,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	Node in the virtual topology of a federated experiment (emulab legacy)
+	Node in the virtual topology of a federated experiment (Emulab
+	legacy).  The fields are the local hostname and the IP addresses
+	of the experimental interfaces(colon-separated).
       </xsd:documentation>
     </xsd:annotation>
@@ -202,5 +250,8 @@
     <xsd:annotation>
       <xsd:documentation>
-	LAN in the virtual topology of a federated experiment (emulab legacy)
+	LAN in the virtual topology of a federated experiment (Emulab legacy).
+	The fields are the name of the LAN/link (vname) the node that
+	this description applies to (vnode), the IP of the connection,
+	and performance information.
       </xsd:documentation>
     </xsd:annotation>
@@ -218,5 +269,5 @@
     <xsd:annotation>
       <xsd:documentation>
-	The virtual topology of a federated experiment (emulab legacy)
+	The virtual topology of a federated experiment (Emulab legacy).
       </xsd:documentation>
     </xsd:annotation>
@@ -232,5 +283,8 @@
     <xsd:annotation>
       <xsd:documentation>
-	Node in the visualization of a federated experiment (emulab legacy)
+	Node in the visualization of a federated experiment (Emulab
+	legacy).  Fields include the local hostname of the node, x,y
+	coordinates in a 2-dimensional representation, and whether the
+	node in the visualization is a host or a LAN.
       </xsd:documentation>
     </xsd:annotation>
@@ -246,5 +300,5 @@
     <xsd:annotation>
       <xsd:documentation>
-	The visualization of a federated experiment (emulab legacy)
+	The visualization of a federated experiment (Emulab legacy)
       </xsd:documentation>
     </xsd:annotation>
@@ -258,5 +312,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	The information needed to create a dynamic project
+	The information needed to create a dynamic project, specifically
+	a project description and the resources in needs access to.
+	This is used by an internal fedd interface.
       </xsd:documentation>
     </xsd:annotation>
@@ -271,5 +327,6 @@
     <xsd:annotation>
       <xsd:documentation>
-	The information needed to create a dynamic project
+	The description of a dynamically created project, used by an
+	internal fedd interface.
       </xsd:documentation>
     </xsd:annotation>
@@ -282,5 +339,5 @@
     <xsd:annotation>
       <xsd:documentation>
-	The description of the federated experiment
+	The description of the federated experiment, in extended ns2.
       </xsd:documentation>
     </xsd:annotation>
@@ -293,5 +350,11 @@
     <xsd:annotation>
       <xsd:documentation>
-	The full on request type.
+	Request for access to a testbed.  It includes the testbed from
+	which resources are being requested (a single service may
+	provide access to many), the user or project requesting access
+	(a testbed making the request will leave both empty), the
+	resources needed, the access keys to be used in the subsequent
+	instantiation and service use, an allocation ID to identify this
+	access in later requests, and scheduling information.
       </xsd:documentation>
     </xsd:annotation>
@@ -321,5 +384,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	The full on response type.
+	Response to an access request.  Includes the allocation, the
+	information needed to access creation and experiment services
+	and scheduling information.
       </xsd:documentation>
     </xsd:annotation>
@@ -336,5 +401,11 @@
     <xsd:annotation>
       <xsd:documentation>
-	A request to embed a federated experiment across testbeds
+	A request to embed a federated experiment across testbeds.  Non-
+	standard local names for testbeds are included in the
+	testbedmap, the user making the request, the experiment
+	description, master testbed, and a suggested experiment name are
+	included.  More than one name can be suggested, either as
+	synonyms (a fedid and a localname) or as choices (multiple
+	localnames).
       </xsd:documentation>
     </xsd:annotation>
@@ -355,5 +426,12 @@
     <xsd:annotation>
       <xsd:documentation>
-	A request to embed a federated experiment across testbeds
+	The reply to a successful creation request.  Includes the
+	information about federants hosting sub-experiments for service
+	access as well as virtual topology and visualization
+	information.  All that information is relative to the requester.
+	ExperimentAccess includes credentials with which one can access
+	the experiment.  These may include a public key necessary to
+	prove possession of the credential and should be treated with
+	care.
       </xsd:documentation>
     </xsd:annotation>
@@ -375,5 +453,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request for an existing experiment's topology
+	Request for an existing experiment's virtual topology.
+	Different information may be returned based on the user's rights
+	to see the topology.
       </xsd:documentation>
     </xsd:annotation>
@@ -386,5 +466,6 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request for an existing experiment's topology
+	The response to a topology request.  Different information may
+	be returned based on the user's rights to see the topology.
       </xsd:documentation>
     </xsd:annotation>
@@ -399,5 +480,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request for an existing experiment's topology
+	Request for an existing experiment's visualization.  This is
+	largely a compatibility service.  Different information may be
+	returned based on the user's rights to see the topology.
       </xsd:documentation>
     </xsd:annotation>
@@ -410,5 +493,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request for an existing experiment's topology
+	An existing experiment's visualization.  This is largely a
+	compatibility service.  Different information may be returned
+	based on the user's rights to see the topology.
       </xsd:documentation>
     </xsd:annotation>
@@ -422,6 +507,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request for an existing experiment's topology
-      </xsd:documentation>
+	A combined topology, visualalization, and federant request.
+	Different information may be returned based on the user's rights
+	to see the topology.  </xsd:documentation>
     </xsd:annotation>
     <xsd:sequence>
@@ -433,6 +519,7 @@
     <xsd:annotation>
       <xsd:documentation>
-	Information on an instantiated experiment.  The createResponse without
-	the secret information
+	Information on an instantiated experiment.  A createResponse
+	without the secret information.  Different information may be
+	returned based on the user's rights to see the topology.
       </xsd:documentation>
     </xsd:annotation>
@@ -452,5 +539,5 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request to terminate an experiment
+	Request to terminate an experiment.
       </xsd:documentation>
     </xsd:annotation>
@@ -463,5 +550,5 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request to terminate an experiment
+	Indication that the experiment has been terminated.
       </xsd:documentation>
     </xsd:annotation>
@@ -474,5 +561,6 @@
     <xsd:annotation>
       <xsd:documentation>
-	Request to run splitter remotely
+	Request to run the CEDL splitter remotely.  This is primarily an
+	internal interface.
       </xsd:documentation>
     </xsd:annotation>
@@ -487,5 +575,5 @@
     <xsd:annotation>
       <xsd:documentation>
-	Remote splitter output
+	Remote splitter output.  Also an internal interface
       </xsd:documentation>
     </xsd:annotation>
@@ -497,4 +585,21 @@
 
   <xsd:complexType name="faultType">
+    <xsd:annotation>
+      <xsd:documentation>
+	Indication that a service has failed.  The code values are
+
+	  1 access denied
+	  2 proxy error
+	  3 badly formed request
+	  4 server configuration error
+	  5 internal error
+	  6 partial instantiation
+	  7 federant error
+
+	Errstr contains the text above corresponding to the code.  Code
+	is always present.  Desc provides additional human-readable data
+	about the error.
+      </xsd:documentation>
+    </xsd:annotation>
     <xsd:sequence>
       <xsd:element name="code" type="xsd:int">
