System Metadata =============== .. module:: SystemMetadata System metadata (often referred to as :term:`sysmeta`) is the information used by DataONE to track and manage objects across the distributed Coordinating and Member Nodes of the network. System metadata documents contain low level information (e.g. size, type, owner, access control rules) about managed content such as science data, science metadata, and resource map objects and obsolescence chains (obsoletes and obsoletedBy). .. figure:: images/sysm_relations.png *Figure 1.* All managed content (science metadata, science data, and resource maps) in DataONE is accompanied by System Metadata (1, 2, 3 respectively). The relationships between science metadata and data object, and thus the structure of a data package, is described by resource maps. In this simple data package, the resource map indicates that the science metadata document *documents* the science data (4), and that the science data *isDocumentedBy* the science metadata (5). System Metadata is maintained dynamically by Coordinating Nodes and some properties are mutable to reflect the current state of an object in the system. Initial properties of system metadata are generated by clients and Member Nodes. After object synchronization, the Coordinating Nodes hold authoritative copies of system metadata. Mirror copies of system metadata are maintained at each of the Coordinating nodes. .. figure:: images/sysm_generate.png *Figure 2.* System metadata is provided by Member Nodes (1) in response to a :func:`MNRead.getSystemMetadata` call by the Coordinating Nodes during the Member Node synchronization process (2). The Coordinating Node updates the system metadata serial number, timestamps and replica location information (3), and the copy of system metada is replicated between the Coordinating Nodes (4). A user will typically retrieve system metadata from the Coordinating Nodes (5) using the :func:`CNRead.getSystemMetadata` call since that is the authoritative source for the information. System metadata are considered operational information needed to run DataONE, and can be read by all Coordinating Nodes and Member Nodes in the course of service provision. In order to reduce issues with third-party tracking of data status information, users can read system metadata for an object if they have the access rights to read the corresponding object which a system metadata record describes. System Metadata elements are partitioned into two classes: metadata elements that must be provided by client software to the DataONE system, and elements that are generated by DataONE itself in the course of managing objects. The mutability of system metadata elements is described in Table 1. **Table 1.** Mutability of system metadata. Values are *Initialized By* different components during creation, and those values are vetted by (*Controlled By*) downstream, authoritative components. Mutable properties are edited through *Edit Method*. .. sqltable:: System Metadata Mutability :header: Property, Mutable?, Initialized By, Controlled By, Edit Method :widths: 3 1 1 1 10 :driver: xlsx :source: source/design/data/SysMetaMutability.xlsx :sql: SELECT Property, Mutable, initializedBy, controlledBy, Method FROM Sheet1; The system metadata schema is expressed in XMLSchema and the development version is available at: https://repository.dataone.org/software/cicore/trunk/d1_schemas/dataonetypes.xsd The most recent release version is available from: https://repository.dataone.org/software/cicore/tags/D1_SCHEMA_xxx This document refers to the current target for release, version 1 which is located at: https://repository.dataone.org/software/cicore/branches/D1_SCHEMA_V1/dataoneTypes.xsd If there are discrepancies between this document and the schema, then the schema shall be considered authoritative. Schema Document --------------- The current development version of the system metadata schema document (version 1.0) is included here for reference. It is located in the source control repository at: https://repository.dataone.org/software/cicore/trunk/d1_schemas/dataonetypes.xsd .. literalinclude:: /d1_schemas_v1/dataonetypes.xsd :language: xml Example Document ---------------- The example instance document included here was auto-generated so does not include useful values. It is included here to provide a general indication as to the structure of a populated system metadata document. .. literalinclude:: /d1_schemas/instance-eg-v11.xml :language: xml