/*  
   This is the BrainML-X protocols subschema describing interactions with
   catalog servers.  Included are a resource description format, a means to
   submit resource descriptions to a catalog server, and a means to query
   a catalog server for resources matching certain criteria.

   - Resource descriptions describe basic information about a resource, such
     as URL and technical contact, as well as what the resource contains and
     how it is accessed.

   - Catalog submissions send one or more resource descriptions to a catalog
     server for indexing.  Previous authentication is required.

   - Catalog queries requests URLs for repositories that serve a certain type
     of data.
 */
targetNamespace "urn:bml/brainml.org:internal/Protocols/5"
namespace "urn:bml/brainml.org:internal/Protocols/5"
namespace bmtl "urn:bml/brainml.org:internal/BrainMetaL/1"
import "http://brainml.org/schemas/internal/BrainMetaL/1/citation.xsd" namespace "urn:bml/brainml.org:internal/BrainMetaL/1"
include "http://brainml.org/schemas/internal/Protocols/5/imperatives.xsd"
abstract element contact { contact-type }
complexType contact-type extends bmtl:entity_element-type {
    ( name { xs:normalizedString }, email { xs:token }, phone { xs:token }? )
}

/*  Person responsible for the resource, determining its contents and policies,
   etc.. */
element administrative_contact { contact-type }

/*  Person responsible for day to day upkeep and technical management of the
   resource. */
element technical_contact { contact-type }

/* Description of a resource suitable as a catalog entry. */
element neuroscience_resource { neuroscience_resource-type }
complexType neuroscience_resource-type extends bmtl:entity_element-type {
    ( short_name { xs:token }, full_name { xs:token }, cataloging_info?, url { xs:anyURI }, administrative_contact, technical_contact, host_resources { xs:string }, characteristics, content, availability, evaluation, comments? )
    
    /* Information on the cataloging of this resource. */
    element cataloging_info {
        ( ( entry_date { xs:dateTime }, modification_date { xs:dateTime }, cataloger { xs:token } )?, ( import_source { xs:anyURI }, foreign_id { xs:token } )? )
    }
    
    /* Description of the overall nature of a resource. */
    element characteristics {
        ( resource_type+, data_format { xs:string }, content_text { xs:string } )
        
        /*  The type or format of the resource (online data store, reagent supply
         house, etc.).  Controlled Vocabulary. */
        element resource_type restricts bmtl:vocab-type {
            attribute domain { xs:token } = "resource type"
        }
    }
    
    /* Description of the neuroscience contents of a resource. */
    element content {
        ( data_type*, neural_structure*, level_or_component*, organism*, technique*, neurobiological_focus*, stage*, disease* )
        
        /*  Keywords describing normal function or disease state relevant to
         resource's contents and/or mission. */
        element data_type restricts bmtl:vocab-type {
            attribute domain { xs:token } = "data type"
        }
        
        /*  Keywords describing brain or body location(s) relevant to
         resource's contents or mission. */
        element neural_structure restricts bmtl:vocab-type {
            attribute domain { xs:token } = "neural structure.structure / location"
        }
        
        /*  Keywords describing brain or body structural component relevant to
      resource's contents and/or mission. */
        element level_or_component restricts bmtl:vocab-type {
            attribute domain { xs:token } = "neural structure.level_or_component"
        }
        
        /*  Keywords describing organism(s) relevant to
         resource's contents and/or mission. */
        element organism restricts bmtl:vocab-type {
            attribute domain { xs:token } = "organism"
        }
        
        /*  Keywords describing technique(s) relevant to
         resource's contents and/or mission. */
        element technique restricts bmtl:vocab-type {
            attribute domain { xs:token } = "technique"
        }
        
        /*  Keywords describing functional system relevant to 
         resource's contents and/or mission. */
        element neurobiological_focus restricts bmtl:vocab-type {
            attribute domain { xs:token } = "functional context.neurobiological_focus"
        }
        
        /*  Keywords describing developmental stage, if any, relevant to
         resource's contents and/or mission. */
        element stage restricts bmtl:vocab-type {
            attribute domain { xs:token } = "functional context.stage"
        }
        
        /*  Keywords describing disease condition, if any, relevant to
         resource's contents and/or mission. */
        element disease restricts bmtl:vocab-type {
            attribute domain { xs:token } = "functional context.disease"
        }
    }
    
    /* Description of availability of / access to the resource. */
    element availability {
        ( access, license?, method+, software_method { xs:string }?, terminology_type?, terminology_description { xs:string }? )
        
        /*  Is this an open resource, is registration required, or is access
         restricted to a particular community, or is this a private resource?
         Controlled vocabulary. */
        element access restricts bmtl:vocab-type {
            attribute domain { xs:token } = "resource availability.access"
        }
        
        /*  License agreement, if any, restricting (re)use or redistribution of
         the data or software tool or other content provided by the resource. */
        element license restricts bmtl:vocab-type {
            attribute domain { xs:token } = "resource availability.license"
        }
        
        /* The main interface for obtaining primary data from the resource. */
        element method restricts bmtl:vocab-type {
            attribute domain { xs:token } = "resource availability.method"
        }
        
        /*  Does this resource use terminology that is shared, open, closed, or
         otherwise situated? */
        element terminology_type restricts bmtl:vocab-type {
            attribute domain { xs:token } = "resource availability.terminology"
        }
    }
    
    /* Evaluation of the resource's utility. */
    element evaluation {
        ( coverage?, utility_text { xs:string } )
        
        /*  Estimate of how central this resource is among others providing the
         same type of content. */
        element coverage restricts bmtl:vocab-type {
            attribute domain { xs:token } = "coverage"
        }
    }
    element comments {
        ( resource_comments { xs:string }?, interface_comments { xs:string }? )
    }
}

/* Catalog query. */
element catalog_query { catalog_query-type }
complexType catalog_query-type extends query-type {
    ( and | or )
}

/* Catalog response. */
element catalog_response { catalog_response-type }
complexType catalog_response-type extends response-type {
    ( repository, )*
}

/* Return component for catalog_response. */
element repository { repository-type }
complexType repository-type {
    
    /* URL to repository site root. */
    attribute url { xs:anyURI }
}

/*  Catalog submission wrapper.  The contents are given as one or more entries
   under this element. */
element catalog_submission { catalog_submission-type }
complexType catalog_submission-type extends submission-type {
    ( neuroscience_resource, )+
}

/*  Catalog update wrapper.  The contents are given as one or more entries
   under this element. */
element catalog_update { catalog_update-type }
complexType catalog_update-type extends submission-type {
    ( neuroscience_resource, )+
}

/*  Catalog submission acknowledgement, which includes a repetition of the user
   name and identifier given with the submission, together with a status
   indicator.  Child submitted_entity elements contain information on the
   individual components of the submission.. */
element catalog_acknowledgement { catalog_acknowledgement-type }
complexType catalog_acknowledgement-type extends acknowledgement-type {
    ( ( submittedEntity, )+ | ( error, )+ )
    
    /*  ID assigned by the server, which may be used to uniquely identify the
      submission (on this server).  If the value "FAILED" is received,
      the submission failed, and 'error' elements under this one specify
      the reasons. */
    attribute submissionID { xs:ID }
}