/*
   This schema specifies top-level elements that BrainML elements should inherit
   from, and utility elements to be used by BrainML schemas and/or instance
   documents.  Included are:
  
   - the Quintessence elements, abstract top-level data "classes"
  
   - a 'link' element for linking between quintessence elements, both within
     and between documents, and for referencing external resources such as
     journal article PDFs
  
   - a 'unit' element which supports reference to unit definitions defined
     in instance documents conforming to the "units" schema
  
   - a 'vocab' element which supports reference to term declarations in
     instance documents conforming to the "vocabulary" schema
  
   - utility complex data type elements
  
   - [temporary] elements defining the structure of a data submission, so that
     instance documents can be validated directly against this.. these will be
     moved to one or more "brainml" schemas defining document types for exchange
*/
targetNamespace "urn:bml/brainml.org:internal/BrainMetaL/1"
namespace "urn:bml/brainml.org:internal/BrainMetaL/1"
namespace xlink "http://www.w3.org/1999/xlink"

import "http://brainml.org/schemas/internal/BrainMetaL/1/xlink.xsd" namespace "http://www.w3.org/1999/xlink"

/* Note: canonical location of the 'xml' schema is
   "http://www.w3.org/2001/xml.xsd", however sometimes this server is down
   or slow, so we use a local copy. */
import "http://brainml.org/schemas/internal/BrainMetaL/1/xml.xsd" namespace "http://www.w3.org/XML/1998/namespace"

/* Wildcard attribute. */
attributeGroup anyExtAttr {
   anyAttribute
}

/*
   Wildcard content supporting any elements and attributes that have namespaces
   outside of this one, w/any attributes.
*/
group anyExtEl {
   ( { any namespace ##other }*, )
}

/*
   Wildcard content supporting any elements and attributes that have namespaces
   outside of this one, w/any attributes.
*/
group anythingExt {
   ( @anyExtEl*, )
}

/*
   Wildcard content supporting any elements and attributes that have namespaces
   outside of this one, w/any attributes.
*/
attributeGroup anythingExt {
   attributeGroup anyExtAttr
}

/*
   Generic element for linking to another element within the same or
   another document.  The href attribute should be of form #id, where 'id'
   is an XML ID in the current document (no whitespace, cannot start with
   number).  This will be resolved relative to the local value of xml:base
   (see http://www.w3.org/TR/xmlbase/).  To ensure a local reference when
   there might be an externally-referencing xml:base value in the context,
   set xml:base="" within the link.
*/
element link { link-type }
complexType link-type {
   attribute xml:base
   required attribute xlink:href
   /* Indicates nature of the referred-to end of the relation. */
   attribute xlink:role
   /*
     If this is a link to another BrainML element (not an external resource),
     the definition of this element is given here, in the form
     URI,element, as in "urn:bml/brainml.org:internal/BrainML/1,experiment".
   */
   attribute dest { xs:anyURI }
}

/* Link that must go to a collection element. */
element link_collection restricts link-type {
      required attribute dest { xs:anyURI } = "urn:bml/brainml.org:internal/BrainMetaL/1,collection" 
}

/* Designates a collection of BrainML elements, identified by links, which may
   themselves go to collections.  More precisely, this element consists of a
   list of zero or more links to other collections, followed by a list of zero
   or more links to non-collection items.  An empty collection is legal.
   The order of the links may be ignored by the processing application unless
   the attribute 'ordered' is set to "true".
   This element can be extended to add any metadata for describing the
   collection that is needed. */
element collection { collection-type }
complexType collection-type {
   ( link_collection*, link* )
   required attribute id { xs:ID }
   /* Optional name for the collection. */
   attribute name { xs:token }
   /* Order of contents may be ignored unless present and set to "true". */
   attribute ordered { xs:boolean }
}


/*
   Element for referencing predefined units.  (Defined in documents conforming
   to units.xsd.  You should subclass / substitute this element to define your
   own semantics.  (See examples.)
*/
element unit { unit-type }
complexType unit-type {
   /* (Optional) Name of the unit (excluding hierarchical context). */
   attribute name {xs:token}
   /* Full URL to the unit's ID in its declaring document. */
   required attribute xlink:href
}


/*
  Type for measured quantities.  The href attribute should be a unit reference,
  as for the 'unit' element.  Inside this element is a decimal value.
  You should subclass / substitute this element to define your own semantics.
  (See examples.)
*/
element measured_quantity { measured_quantity-type }
complexType measured_quantity-type {
   xs:decimal
   /* Full URL to the unit's ID in its declaring document. */
   required attribute xlink:href
   /* (Optional) Name of the unit (excluding hierarchical context). */
   attribute name {xs:token}
}


/*
   Type for referencing predefined vocabulary terms.
*/
element vocab { vocab-type }
complexType vocab-type {
   /* Domain of applicability for the term (including hierarchical context). */
   attribute domain {xs:token}
   /* Name of the term (including hierarchical context). */
   attribute term {xs:token}
   /* Full URL to the term's ID in its declaring document. */
   required attribute xlink:href
}


/* A single data point, possibly multi-dimensional. */
element datum { xs:token }

/* 
   Type for expressing dimensions of a dataset, that is, its length if it is
   a one-dimensional series, the number of arrays and their length for a
   two-dimensional grid, and so on.  For nonrectangular datasets where the
   lengths of subarrays may vary, use '*' instead of a number.
*/
simpleType dimension-type { union { xs:unsignedInt; xs:token { "*"  }  } }

/*
   Type for expressing the type of data points in a dataset.  Valid values are
   integer, decimal, and string.  Integer and decimal types can be of arbitrary
   size and precision, however BrainML applications MAY process these as 4-byte
   signed integers, and 8-byte IEEE doubles respectively.  Strings are in
   whatever encoding the XML document itself declares.  Custom refers to
   anything not covered by the first three, such as binary images, sound files,
   etc..
*/
simpleType datatype-type { xs:token { /integer|decimal|string|custom/ } }

/*
   Attributes describing a dataset: the sizes of its array(s), and the type
   of its data points.
*/
attributeGroup dataset-common {
   /*
      Describes the dimensions of the dataset, as a space-separated list
      consisting of numbers or "*".  Each number indicates the number of
      values the dataset contains on a dimension.  Thus, a one-dimensional
      dataset such as a time series will have just one number -- the length
      of the time series.  A two-dimensional dataset such as a grid of values
      has two numbers -- the sizes of the X and Y axes of the grid.
      Alternatively, two numbers may be used to indicate a number of tuples
      and the length of each tuple.  (Containing element should specify which
      usage is valid.)  For example, "* 2" indicates a list of ordered pairs.
      Non-rectangular or unknown length data is accomodated through use of the
      special '*' value.
      A list of five time series, each of a different length, would have
      dimensions "5 *".  Each individual time series entry contained under this
      would have its own dimensions entry of a single number giving its length.
   */
   required attribute dimensions { simpleType { list { dimension-type  }  } { length = [ 1, ]  } }

   /*
      The data type of this data set.  Valid values are integer, decimal, and
      string.  Integer and decimal types can be of arbitrary size and
      precision, however BrainML applications MAY process these as 4-byte
      signed integers, and 8-byte IEEE doubles respectively.  Strings are in
      whatever encoding the XML document itself declares.
   */
   required attribute type { datatype-type }
}

/*
   Data container:  Full XML format, where every data value is contained in
   its own tag, and dimensional structure is reflected in tag containment.
*/
element datasetX substitutes dataset {
   ( ( datasetX | datasetC | datasetB | datasetR )+ | datum+ )
   attributeGroup dataset-common
}

/*
   Data container:  Whitespace- or comma-separated values contained under
   a single XML tag.  Rectangular multi-dimensional data is given as a linear
   array which must be stepped through by the application.
*/
element datasetC substitutes dataset {
   xs:string
   /* Character(s) used to delimit individual data values. */
   attribute delimiter { xs:normalizedString }
   /* 
      Characters used to delimit dimensional groups in the dataset.  The left
      and right delimiters should be given, as in "()".  Group delimiters are
      required to express multi-dimensional nonrectangular datasets.  For
      example, an integer dataset with dimensions "2 *" might be expressed
      as '(23,25,29) (25,26)'.
   */
   attribute \group { xs:normalizedString }
   attributeGroup dataset-common
}

/*
   Data container: Base-64 encoded binary, in which values are encoded in IEEE
   standard, network byte order.  Rectangular multi-dimensional data is given
   as a linear array as in the whitespace/comma-separated case.
*/
element datasetB substitutes dataset {
   xs:base64Binary
   attributeGroup dataset-common
}

/*
   Data reference: a reference to external data.  The contents of this element
   should be a URI pointing to the data.  The 'formatType' and 'formatRef'
   attributes should describe the data format and the optional 'info' attribute
   can be used for application- or format-specific information.
*/
element datasetR substitutes dataset {
   xs:anyURI
   attributeGroup dataset-common
   /*
     A short string describing the format of the referenced unit.  This could
     be a MIME string if such exists for this data type.
   */
   required attribute formatType { xs:normalizedString }
   /*
     A URL to a specification or description of the format of the referenced
     unit.
   */
   required attribute formatRef { xs:anyURI }
   /*
     Any required additional information describing this file or its relation to
     others in this dataset may go here.
   */
   attribute info { xs:string}
}

/*
   Superclass for different dataset formats.
*/
abstract element dataset { xs:anyType }

/*
   Consists of two datasets.  The first contains the values, the second,
   which should have exactly the same dimensions, contains the labels
   (as strings).
*/
element labeled_dataset {
   ( dataset[2,2] )
}


/*
   Quintessence elements.  These simply allow an unlimited content model
   beneath them, but explicitly declare some optional contents so that
   BrainML applications know to expect them.
   Common content defining an optional ID and an optional xml:base.
   The ID is used as a link target and must be unique within a document.
   The xml:base is used to direct links contained within a given element
   to resolve to an external document.
*/
group quintessence-common-content {
   ( link*, )
}

attributeGroup quintessence-common-content {
   /* This attribute is needed so that others may link to it. */
   attribute id { xs:ID }
   /* Used to indicate URL that links under this element and its children
      should resolve relative to. */
   attribute xml:base
}


/*
   Quintessence element.  These simply allow an unlimited content model
   beneath them, but explicitly declare some optional contents so that
   BrainML applications know to expect them.
   Data element for numerical data and container structures, including
   entire submission.
*/
abstract element data_element { data_element-type }
complexType data_element-type {
   ( @quintessence-common-content, )
   attributeGroup quintessence-common-content
}


/*
   Quintessence element.  These simply allow an unlimited content model
   beneath them, but explicitly declare some optional contents so that
   BrainML applications know to expect them.
   Entity element for recording sites, chemical substances, genes, anything
   that has a physical existence.
*/
abstract element entity_element { entity_element-type }
complexType entity_element-type {
   ( @quintessence-common-content, )
   attributeGroup quintessence-common-content
}


/*
   Quintessence element.  These simply allow an unlimited content model
   beneath them, but explicitly declare some optional contents so that
   BrainML applications know to expect them.
   Method element for methods, techniques, procedures, analytical algorithms.
*/
abstract element method_element { method_element-type }
complexType method_element-type {
   ( @quintessence-common-content, )
   attributeGroup quintessence-common-content
}


/*
   Quintessence element.  These simply allow an unlimited content model
   beneath them, but explicitly declare some optional contents so that
   BrainML applications know to expect them.
   Model element for theories, hypotheses.
*/
abstract element model_element { model_element-type }
complexType model_element-type {
   @quintessence-common-content
   attributeGroup quintessence-common-content
}


/*
   Quintessence element.  These simply allow an unlimited content model
   beneath them, but explicitly declare some optional contents so that
   BrainML applications know to expect them.
   Reference element for bibliographic and other references to external
   material.
*/
abstract element reference_element { reference_element-type }
complexType reference_element-type {
   ( @quintessence-common-content, )
   attributeGroup quintessence-common-content
}


/* Top-level element for a stand-alone document containing a dataset. */
element data_document {
   ( dataset | labeled_dataset )*
}