# Structure and Conventions

## The XCEDE 2 Dataset

An XCEDE 2 dataset is a data repository (stored in files, databases, or using other storage mechanisms) that can be represented as a collection of one or more XML documents, each of which validates against the XCEDE 2 XML schema (). The XCEDE 2 specification does not prescribe any particular mechanism by which these documents are located, stored, grouped, or linked, though XCEDE 2 allows certain XML elements to link to other target elements and to optionally specify URLs as hints as to the location of the documents containing these targets.

For example, a given XCEDE 2 dataset may be stored as a single XML document, or a collection of files in a single directory on a file system, or may be distributed within a hierarchical directory structure (which may or may not reflect the structure of the data within), or may be stored within a database accessible by query through a web interface. The semantics of the dataset should be fully reflected in the XML representation, and should not be dependent on how the dataset is stored.

A schema-compliant XCEDE 2 document must be a valid XML 1.0 document XML10, and must have one root element, `<XCEDE>`, which (like all other XCEDE 2 elements) is in the `http://www.xcede.org/xcede-2` XML namespace.

Several major components of the XCEDE 2 dataset are represented as children of the XCEDE root element. These components include:

- Experiment hierarchy

  The components in the experiment hierarchy are represented by elements `<project>`, `<subject>`, `<visit>`, `<study>`, `<episode>`, `<acquisition>`. These are described in more detail in .

- Data

  The element `<data>` is used to store actual data within the XML document. Examples include events () and assessments ().

- Data resources

  Represented by the element `<resource>`, these point to external files which store actual data. See .

- Analyses

  The `<analysis>` element encapsulates metadata about data that is derived from one or more inputs, whose data may be represented by other XCEDE components, such as `<data>` or data resources. See .

- Protocols

  Structures to describe the expected course of an experimental paradigm are provided by the `<protocol>` element. See .

Other XCEDE components appear as subcomponents of other XCEDE structures:

- Data provenance

  The `<provenance>` element appears in the types analysis_t (on which the `<analysis>` element is based) and dataResource_t (one of the available data models for the top-level `<resource>` element). See .

- Comments and annotations

  The `<commentList>` and `<annotationList>` elements provide mechanisms to store, respectively, descriptive text regarding the real-world entities or concepts represented by the associated XML element, or about the stored XML element itself. These are available in all elements based on abstract_container_t, which includes all the hierarchy elements and `<analysis>`.

- Informational resources

  These point to documentation that may illuminate aspects of the data, data collection, protocol, etc. -- these might include peer-reviewed publications, equipment manuals, and others. Informational resources are represented in the type informationResource_t which is used in the `<resourceList>` element in abstract_container_t (as with the comments and annotations).

- Terminology

  Various elements in XCEDE 2 include the attribute group terminology_ag or use the type `terminologyString`, which allow the user to associate them with terms from particular nomenclatures/ontologies. For example, a subject's `<species>` may refer to a standard term listed in a well-known public nomenclature. See .

## XCEDE 2 Schema conventions

The XCEDE XML document structure is defined using W3C XML Schema language XMLSchema10. With a few exceptions, the XCEDE 2 XML schema subscribes to the following conventions and best practices.

Naming and capitalization

- Element and attribute names are alphanumeric (`<project>`). All letters are lowercase, with the exception of acronyms, which are uppercase (`<XCEDE>`, `projectID`), and, in multi-word names, the initial letters of the second and following words which are capitalized (`<dataResourceRef>`). For the purposes of this rule, `ID` (for identifier) is considered an acronym.

- Schema type names (which do not appear in XML instance documents except in `xsi:type` attributes) follow the same naming conventions as element and attribute names, but have the `_t` suffix (analysis_t). If the type is abstract, then it has an `abstract_` prefix (abstract_container_t).

- Attribute group names (which do not appear in XML instance documents) follow the same naming conventions as element and attribute names, but have the `_ag` suffix (allLevelExternalIDs_ag).

Schema best practices

- Follow the schema versioning best practices recommended by Roger Costello in CostelloSchemaVersioning. Some of the implications are listed below:

  - The XCEDE namespace will change for major versions, but not minor versions. So, the namespace is as follows: `http://www.xcede.org/xcede-major_version`. For example: `http://www.xcede.org/xcede-2`

  - XSD files will be named `xcede-VERSION-DOMAIN`. For example: `xcede-2.0-core.xsd`

  - All elements should have a corresponding named `complexType`. For example: `<project>` is of type project_t.

  - The schema prescribes that some elements precede or follow other elements -- document creators should follow this strictly. However, applications should be written without expecting a particular element order, in case later versions of the schema change the order of elements. That is, be conservative in what you write, but liberal in what you accept.

    This is not to say that element order is not important -- the relative order of multiple elements with the same name should be preserved and can be relied upon by applications. So, if the schema specifies the content model of an element to have multiple `<A>` children and then multiple `<B>` children, applications should treat a dataset the same whether all the `<A>` children came before or after (or even interleaved with) the `<B>` elements, but all `<A>` elements should be presented to the application in the same order they appear in the document. The corollary is that the semantics of any XCEDE 2 element must not depend on the order in which differently-named children are presented in the document.

Document validation

- The structure of an XCEDE 2 document can be validated using the XCEDE 2 Core schema. Several XML Schema validators are available to perform this task. Validating against the schema will ensure that generic XCEDE 2 parsers can read the document.

  Users may wish to perform content-based validation of an XCEDE document, for example, to make sure that MR image metadata stored in an XCEDE document have certain required fields such as TR, TE, magnet field strength, etc., and that their values fall within reasonable ranges. This kind of validation is not possible using XML Schema. However, other content-based schema languages exist for this purpose, most notably Schematron Schematron. As long as the XCEDE 2 Core schema is structurally sufficient to represent data for a given project or type of data, using a content-based schema language such as Schematron allows users to restrict or specialize the content of XCEDE documents without needing to modify or extend from the XCEDE 2 Core schema itself.