Using OME-XML schema elements ============================= This sections explains how to use OME schema elements in your own XML files. .. note:: The correct attribution for work derived from our schema files under the Creative Commons licence is: **"This work is derived in part from the OME specification. Copyright (C) 2002-2017 Open Microscopy Environment"** We encourage people to make use of the OME Data Model as a whole by using the OME-XML and OME-TIFF formats directly. If you need to store additional user-specific data, the correct approach is to embed it within the OME Data Model using Structured Annotations. These provide a powerful and flexible way of storing your own custom data alongside the OME model metadata, while still maintaining full compatibility with OME-XML and OME-TIFF files, ensuring your file can be read by any application supporting these formats. If this approach will not work for you, we would encourage you to contact us via the :forum:`forums <>` and :mailinglist:`mailing lists <>` as we may be able to help you structure your additions so compatibility can be maintained. Fully compatible and exchangeable files is what this project all is about, so we try to support this as much as we can. If there is still no possible approach for your data that can maintain compatibility with OME-XML or OME-TIFF, then what follows is the best practice for this situation. Things to avoid --------------- #. Adding arbitrary items to the OME Model and still calling it OME-XML or OME-TIFF We cannot stress enough that this is a **very bad** approach! If you simply insert your own custom nodes at arbitrary points within the XML document, you will produce a broken/invalid OME-XML or OME-TIFF file. As the outer wrapping looks like an OME file, people will expect it to work like an OME file. Applications are likely to fail to import the file as they will produce an error as they encounter your additional XML elements. This will frustrate end users and is likely to produce reports of broken applications. These tend to ultimately propagate back to our development team and we have to investigate, which eats into the time we have available to work on new features and formats. #. Adding or removing arbitrary items to/from the OME Model by copying our structure and calling it something else This is also **not** a good approach. If you copy the OME Model and then make changes (whether by deletion or addition) you are also producing a broken/invalid file, even if you call it something else. We have defined parts of the model that can be omitted (marked as optional in the schema), and defined points where additions can be made (inside the Structured Annotations). It is important to us that we have some control over additions and omissions as it allows us to produce a format that has the widest compatibility. Even though the specifications we produce are now released under a less restrictive license, we do not encourage this approach. We want anyone who encounters an OME node in an XML document to be able to trust its structure, as well as validate and parse it. #. A 'pick and mix' by copying our structure While we have changed the licence the schema files for the OME Model are released under to allow this approach, we would not encourage this. You should **not** need to copy pieces of our definitions and place them directly in your schema documents. Direct copying of our structure is not necessary as XML already has a method of including items from another schema, **see below**. From our point of view this is important as it allows us to control which parts of our model can be used as stand-alone objects in others' work. Correct approaches ------------------ If you have to define your own schema that will make use of our OME model, there are two approaches: #. Wrapping our entire OME Model in your custom model The entire OME Model, when used in an instance document, is completely contained inside the ```` node. It is possible to include a complete ```` node from the OME schema within your own custom XML node. While this does not maintain direct compatibility with the OME-XML and OME-TIFF file formats, it keeps all of the OME Model data together as a single block, that can be easily extracted from your custom XML nodes and passed to a standard OME-XML parser for it to interpret. It only takes a single line of XML Schema Description Language to include the whole model like this. We would always see this wrapping of the **entire OME model** as the best approach to take if you have to define your own custom model. It is also the best way of future-proofing yourself, as an ```` node included like this will be easier to upgrade to newer schema releases using our standard transform. #. A 'pick and mix' by referencing parts of our structure The least desirable valid approach is to individually include small independent parts of the model. Any of the items defined at the top level of the OME schema may be included individually within your custom model. If you take this approach, you must understand that including a node also includes those nodes below it, i.e. including LightSource also includes Laser, Arc etc. This approach does let you select individual parts of our OME model to include, but also lets us control which parts of the model are available for inclusion. Any reading/writing code for OME model pieces stored in this form will have to be custom written, as standard OME model parsers will not be able to process the pieces. .. note:: With either of these approaches please acknowledge our work by including in the appropriate place in your software or project documentation: **"This work is derived in part from the OME specification. Copyright (C) 2002-2017 Open Microscopy Environment"** Worked examples --------------- Here are a few examples of how to define a link to the OME model from within your custom schema file and instance documents. sample-third-party.xml '''''''''''''''''''''' This is an instance document - the xml file that contains your data and is structured to conform to your custom schema specification: :: 2010-02-23T12:51:30 This file has ```` followed by the ```` node, then ````. Apart from the xml namespace and schema location attributes on the ```` node, the file is the same as though the OME model was part of your custom namespace. sample-third-party.xsd '''''''''''''''''''''' In order to define the easy-to-use structure described in the sample-third-party.xml file, you need to add three things (marked ``****``) to your schema specification document: :: Open Microscopy Environment OME Sample Third Party Copyright 2016 OME. sample-third-party-pieces.xml ''''''''''''''''''''''''''''' If you want to import only a few pieces of the OME Model, this example illustrates how to include ```` and ````: :: sample-third-party-pieces.xsd ''''''''''''''''''''''''''''' In order to define this sample-third-party-pieces.xml structure, you need to add four lines (marked ``****``) to your schema specification document. The first two lines are the same as the previous schema specification, then add one line for each of the two included nodes: :: Open Microscopy Environment OME Sample Third Party Copyright 2016 OME. Possible included objects ''''''''''''''''''''''''' .. hlist:: :columns: 2 - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` *(part of the Map key/value structure)* - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ```` - ````