/* 
   This is the BrainML-X protocols subschema describing generic imperatives
   for query, response, submission, and acknowledgement.  These are never used
   directly, but are extended from for catalog and data interactions.
 */
targetNamespace "urn:bml/brainml.org:internal/Protocols/5"
namespace "urn:bml/brainml.org:internal/Protocols/5"
namespace xlink "http://www.w3.org/1999/xlink"
import "http://brainml.org/schemas/internal/BrainMetaL/1/xml.xsd" namespace "http://www.w3.org/XML/1998/namespace"
import "http://brainml.org/schemas/internal/BrainMetaL/1/xlink.xsd" namespace "http://www.w3.org/1999/xlink"

/*  Common superclass for different types of BrainML-X queries.
   Do not use directly. */
abstract element query { query-type }
complexType query-type {
    
    /*  User ID (account name) of the submitter.  Optional for queries, but some
      servers may require. */
    attribute userID { xs:token }
    
    /* 
      Authorization code.  BrainML-X does not currently define authentication
      methods, but assumes that SSL or similar will be used.  Depending on the
      method, it may or may not be necessary to include an authentication
      marker, digital signature, or hash / MD5 value with the content itself.
      Optional for queries, but some servers may require.
 */
    attribute authKey { xs:token }
    
    /* 
      This is an arbitrary identifier supplied by the client that it can use
      to match up the server's response with the submission (if multiple
      submissions are being sent in a single session).  Optional.
 */
    attribute identifier { xs:token }
    
    /* Specify schema namespace starting point for contained references. */
    attribute xml:base
}

/*  Common superclass for different types of BrainML-X query responses.
   Do not use directly. */
abstract element response { response-type }
complexType response-type {
    
    /* Repeats value given with submission. */
    attribute identifier { xs:token }
    
    /* Specify schema namespace starting point for contained references. */
    attribute xml:base
}

/*  Common superclass for different types of BrainML-X submissions.
   Do not use directly. */
element submission { submission-type }
complexType submission-type {
    
    /* User ID (account name) of the submitter. */
    required attribute userID { xs:token }
    
    /* 
      Authorization code.  BrainML-X defines but does not mandate an
      authentication method  Depending on the method, it may or may not
      be necessary to include an authentication marker, digital signature,
      or hash / MD5 value with the content itself.
 */
    attribute authKey { xs:token }
    
    /* 
      This is an arbitrary identifier supplied by the client that it can use
      to match up the server's response with the submission (if multiple
      submissions are being sent in a single session).
 */
    attribute identifier { xs:token }
}

/*  Common superclass for different types of BrainML-X submission
   acknowledgements.  Do not use directly. */
element acknowledgement { acknowledgement-type }
complexType acknowledgement-type {
    
    /* Repeats value given with submission. */
    required attribute userID { xs:token }
    
    /* Repeats value given with submission. */
    attribute identifier { xs:token }
}

/*  Generic error element, returned as sole element for any type of query
   generating an error.  Includes a numeric error code.  The contents of
   the element include a description of the type as well as any particular
   information about what went wrong. */
element error { error-type }
complexType error-type {
    xs:string
    
    /*  Code is a positive integer code for the type of error.
      Codes below 100 are reserved for BrainML use. */
    attribute code { xs:positiveInteger }
}

/* Compositor for use in catalog and data queries. */
complexType compositor-type {
    ( and | or | \field | entity | model )+
}

/* Compositor for use in catalog and data queries. */
element and { compositor-type }

/* Compositor for use in catalog and data queries. */
element or { compositor-type }

/*  Used in catalog_query (to specify a model whose presence is being
   queried for) and bml_resource (to list a supported model).
   The model is specified by its namespace. */
element model { model-type }
complexType model-type {
    ( entity*, term* )
    
    /*  The full namespace of the model being specified.  If this is left
      out, the value from the prevailing xml:base attribute is used. */
    attribute \namespace { xs:anyURI }
}

/* Type for specifying a controlled vocabulary term in a model. */
element term {
    xs:token
    required attribute xlink:href
}

/*  Type for specifying catalog query conditions and data query return content.
   The default for each of 'fields', 'contents', and 'subclasses' is "all". */
element entity { entity-type }
complexType entity-type {
    ( entity | \field )*
    
    /*  Specifies namespace of entity's model.  If this is left
      out, the value from the prevailing xml:base attribute is used. */
    attribute \namespace { xs:anyURI }
    
    /* Specifies an entity local name. */
    required attribute name { xs:normalizedString }
    
    /*  Specifies which fields are to be returned for the entity.  If absent,
      all fields are returned.  If present, should have the value "specified",
      indicating fields specified by child elements should be returned. */
    attribute fields { xs:token { /specified/  } }
    
    /*  Specifies which child entities of the given entity should be returned.
      If absent, all possible child elements will be returned.  If present,
      should have the value "specified", indicating only entities specified by
      child elements should be returned. */
    attribute contents { xs:token { /specified/  } }
    
    /*  Specifies which subclass entities of the given entity should be
      returned.  If absent, all subclasses are returned.  If present, should
      have the value "none", meaning no subclass entities returned.  (It is
      not possible to specify individual subclasses at this time.) */
    attribute subclasses { xs:token { /none/  } }
    
    /* Specify schema namespace starting point for contained references. */
    attribute xml:base
}

/* Specifies a field constraint in a catalog or data query. */
element \field { field-type }
complexType field-type {
    
    /*  Specifies namespace of entity's model.  If this is left
      out, the value from the prevailing xml:base attribute is used. */
    attribute \namespace { xs:anyURI }
    
    /* Specifies the entity the field is in (only needed if ambiguous). */
    attribute entity { xs:normalizedString }
    
    /* Specifies the field on which constraints are being laid in a query. */
    required attribute name { xs:normalizedString }
    
    /* Constraint specifier: field's value must equal this value. */
    attribute value { xs:string }
    
    /* Constraint specifier: field's value must be greater than or equal to this value. */
    attribute valueMin { xs:decimal }
    
    /* Constraint specifier: field's value must be less than or equal to this value. */
    attribute valueMax { xs:decimal }
    
    /* Constraint specifier: field's value must be one of the values (comma-separated and enclosed in "double quotes" if necessary) given. */
    attribute values { xs:string }
}

/*  Element used to identify and report the server-assigned ID for a component
   of a submission.  One element will be given for each component submitted. */
element submittedEntity { submittedEntity-type }
complexType submittedEntity-type {
    
    /*  Type of BrainML entity, given as "namespace,name".  E.g.,
      "urn:bml/brainml.org:internal/Protocols/5,neuroscience_resource". */
    attribute type { xs:anyURI }
    
    /* Server-assigned ID for this submission component. */
    attribute id { xs:ID }
}