The current version is 0.6.7
The MXLIMS data model is a collaborative data model to serve for both API specification and potentially as the basis for data storage solutions, for macromolecular crystallography and related scientific areas. The model is implemented as JSON schemas, with pydantic classes and html documentation generated therefrom.
For general documentation see docs/Overview.pdf
docs/examples contain example JSON files (not necessarily from the very latest version) and mapping files, showing the mapping between MXLIMS and other formats.
For a detailed snapshot of the MXLIMS model as of early 2025 see MXLIMS_presentation_2025.pdf
For model documentation see docs/html, where docs/html/MxlimsMessage.html is the starting point, for covering the entire model.
MXCuBE is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
MXCuBE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with MXCuBE. If not, see https://www.gnu.org/licenses/.
There is no need for particular installation. To make use of MXLIMS you simply download and use the JSON schemas. Html documentation and a Pydantic Python implementation are autogenerated from the JSON schemas and can be downloaded as well, or regenerated in place.
The JSON schemas in mxlims/schemas are the authoritative version of the data model. They are organised as follows:
-
schemas/core contain the abstract classes that define the links and foreign keys that are used to represent the model in a (MongoDB-type) database.
-
schemas/datatypes contain all datatypes, i.e. schemas for data that do not have an object ID, compare by value, and that can be used in any context. Examples are the definitions of enumerations (e.g. space group names), or unit cells.
-
schemas/data contain the definitions of all fields for each supported object, those that would be represented as metadata in an ICAT-type database. These can be used with the GeneralMessage.json to represent any combination of objects, but they lack 1) the faculty for hierarchically nesting objects, 2) the constraints on which types of objects can be linked, the links being defined only by untyped foreign keys.
-
schemas/objects contain the complete objects, inheriting the data fields (from schemas/data) . and the core objects (from schemas/core) and adding type specifications for the inter-object links that are allowed for the particular object (e.g. Pucks cna contain Pins, but not vice versa).
-
schemas/references contain schemas that define references to particular object types. These are used both as part of the specification and for JSON messages; their contents is derived from the definitions in schemas/data, using the mxlims/impl/generate_code.py script. Note that while the reference are used as-is in specifying JSON documents, they are not translated directly to the AP implementations. These use instead the direct storage of target uuids, with field names like 'sourceId' or 'inputDataIds', and with derived field names like 'source', 'logisticalSamples', or 'inputData' to access the linked-to objects. More detail can be found in the Overview.pdf document.
docs/html contains linked html files for all JSON objects and datatypes in the model.
The documentation is generated using the program https://coveooss.github.io/json-schema-for-humans/#/ with the command (starting in the mxlims_data_model directory)
generate-schema-doc --config-file docs/schemadoc_config.json schemas docs/html
To cover the entire model starting from the top containers you should begin with the file doc/html/MxlimsMessage.html as this message can incorporate any object in the model.
There are examples of mxlims messages in docs/examples
The pydantic files live in mxlims/pydantic; they are generated from the JSON schemas in part using https://docs.pydantic.dev/latest/integrations/datamodel_code_generator/
The generated Pydantic for data and datatypes is correct, but the complete API requires also a manually coded im[plementation class, and code generation procedures for pydantic/objects.
There is a prototype Python implementation, generated using the mxlims/impl/generate_code.py script. There is also a test MXCuBE integration. See the relevant mxcubecore WIP pull requests for details.
For getting the full benefit of the MXLIMS model and standardisation you should connect your applications and LIMS to MXLIMS using the API. As a preliminary measure there is an application for converting between simple spreadheet (one-line-per-experiment) formats amd MXLIMS, using a single mapping file. For a working implementation see mxlims/conversion/