Changes for June 2016
=====================


The list of the key changes for the June 2016 major release of the
OME-XML data model. This schema release will tie in with the Bio-Formats
5.2 release.

The new major release of the schema has a new namespace and all version
numbers are reset to 1. As a major release, any file that validated
correctly using the last major release will probably not validate
correctly using this new release. Some files that failed to validate
before will now be valid. It is important to update any file readers and
writers to understand the changes.

This schema uses the new namespace:

::

    http://www.openmicroscopy.org/Schemas/OME/2016-06/

All the schema files have been unified into a single :file:`ome.xsd` file
located at this namespace. The version number of this schema file is 1.

Overview of changes
-------------------

- This release will be implemented in Bio-Formats 5.2 and OMERO 5.3.
- This release introduces the concept of Folders, a new model object which may
  contain Images, ROIs and other Folders, and which has a strict tree
  hierarchy.


Details
^^^^^^^

- The model element ``Folder`` was added. A Folder specifies a possibly
  heterogeneous collection of data and may contain other Folders, Images and
  ROIs. Data may be in multiple Folders but a Folder may not be in more than
  one other Folder, giving a strict tree hierarchy. The primary driver for
  this addition is to allow the organization of ROI elements into hierarchical
  structures (see this `Folders blog post <http://blog.openmicroscopy.org/data-model/future-plans/2016/05/23/folders-upcoming/>`_ for further discussion).
- The ROI properties ``ROI.Namespace``, ``Shape.Linecap`` and
  ``Shape.Visible`` have been dropped. This simplifies graphical aspects in
  the data model in favor of more generic enumerated values independent of the
  rendering framework, making it easier to implement across clients (see this
  `Design issue <https://github.com/ome/design/issues/19>`_ for an
  example discussion).
- The ``Marker`` enumeration has been reduced to ``Arrow`` only, dropping
  ``Circle`` and ``Square``. This affects the ``Line.MarkerStart``,
  ``Line.MarkerEnd``, ``Polyline.MarkerStart`` and ``Polyline.MarkerEnd``
  attributes. As with the ROI property changes, these are also intended to
  simplify the graphical aspects of the data model.

The following are simplifications for code generation purposes and have
no functional effects:

- The model elements ``LightSource`` and ``Shape`` have become abstract
  classes, meaning they are now complexTypes in the :file:`.xsd`. This
  provides a more intuitive object-oriented design (e.g. Rectangle is a type
  of Shape rather than Shape containing a Rectangle) and simplifies the data
  representation (schema) as well as the code generation because two different
  ways to model inheritance and polymorphism have been changed to one.
- The ``MapPairs`` model element has been removed as an unnecessary container
  which is superseded by using the maps directly in the generated code.
- The ``Map`` model element has been made a complexType. This element was
  never used directly, only as a base, so the change allows for the removal of
  a redundant model object.
- xsd:appinfo has been extended to provide more detail for enumeration code
  generation, in particular for units.

Upgrading and Downgrading
-------------------------

The XSLT transforms between January 2015 and June 2016 versions are
available here:

`http://www.openmicroscopy.org/Schemas/Transforms/2015-01-to-2016-06.xsl <http://www.openmicroscopy.org/Schemas/Transforms/2015-01-to-2016-06.xsl>`_

`http://www.openmicroscopy.org/Schemas/Transforms/2016-06-to-2015-01.xsl <http://www.openmicroscopy.org/Schemas/Transforms/2016-06-to-2015-01.xsl>`_