.. WARNING! This file is automatically generated. Edits will be lost. Data Types in CICore -------------------- .. module:: Types :synopsis: Catalog of data types (structures) used by the DataONE cicore. **Quick Reference** - :class:`Types.AccessPolicy` - :class:`Types.AccessRule` - :class:`Types.Checksum` - :class:`Types.ChecksumAlgorithm` - :class:`Types.ChecksumAlgorithmList` - :class:`Types.CrontabEntry` - :class:`Types.CrontabEntrySeconds` - :class:`Types.Event` - :class:`Types.Group` - :class:`Types.Identifier` - :class:`Types.Log` - :class:`Types.LogEntry` - :class:`Types.Node` - :class:`Types.NodeList` - :class:`Types.NodeReference` - :class:`Types.NodeReplicationPolicy` - :class:`Types.NodeState` - :class:`Types.NodeType` - :class:`Types.NonEmptyNoWhitespaceString800` - :class:`Types.NonEmptyString` - :class:`Types.NonEmptyString800` - :class:`Types.ObjectFormat` - :class:`Types.ObjectFormatIdentifier` - :class:`Types.ObjectFormatList` - :class:`Types.ObjectInfo` - :class:`Types.ObjectList` - :class:`Types.ObjectLocation` - :class:`Types.ObjectLocationList` - :class:`Types.Permission` - :class:`Types.Person` - :class:`Types.Ping` - :class:`Types.Replica` - :class:`Types.ReplicationPolicy` - :class:`Types.ReplicationStatus` - :class:`Types.Schedule` - :class:`Types.Service` - :class:`Types.ServiceMethodRestriction` - :class:`Types.ServiceName` - :class:`Types.ServiceVersion` - :class:`Types.Services` - :class:`Types.Session` - :class:`Types.Slice` - :class:`Types.Subject` - :class:`Types.SubjectInfo` - :class:`Types.SubjectList` - :class:`Types.Synchronization` - :class:`Types.SystemMetadata` .. image:: images/classes_combined.png .. @startuml images/classes_combined.png ChecksumAlgorithm --|> xs.string CrontabEntry --|> xs.token CrontabEntrySeconds --|> xs.token enum Event Event : create Event : read Event : update Event : delete Event : replicate Event : synchronization_failed Event : replication_failed enum NodeState NodeState : up NodeState : down NodeState : unknown enum NodeType NodeType : mn NodeType : cn NodeType : Monitor NonEmptyString --|> xs.string ObjectFormatIdentifier --|> NonEmptyString NonEmptyString800 --|> NonEmptyString NonEmptyNoWhitespaceString800 --|> NonEmptyString800 enum Permission Permission : read Permission : write Permission : changePermission enum ReplicationStatus ReplicationStatus : queued ReplicationStatus : requested ReplicationStatus : completed ReplicationStatus : failed ReplicationStatus : invalidated ServiceName --|> NonEmptyString ServiceVersion --|> NonEmptyString class AccessPolicy { + allow : AccessRule[1..*] } AccessPolicy .. AccessRule class AccessRule { + subject : Subject[1..*] + permission : Permission[1..*] } AccessRule .. Subject AccessRule .. Permission class Checksum { + algorithm : ChecksumAlgorithm } Checksum .. ChecksumAlgorithm Checksum --|> xs.string class ChecksumAlgorithmList { + algorithm : ChecksumAlgorithm[1..*] } ChecksumAlgorithmList .. ChecksumAlgorithm class Group { + subject : Subject[1..1] + groupName : NonEmptyString[1..1] + hasMember : Subject[0..*] + rightsHolder : Subject[1..*] } Group .. Subject Group .. NonEmptyString class Identifier { } Identifier --|> NonEmptyNoWhitespaceString800 class Log { + logEntry : LogEntry[0..*] } Log .. LogEntry Log --|> Slice class LogEntry { + entryId : NonEmptyString[1..1] + identifier : Identifier[1..1] + ipAddress : xs.string[1..1] + userAgent : xs.string[1..1] + subject : Subject[1..1] + event : Event[1..1] + dateLogged : xs.dateTime[1..1] + nodeIdentifier : NodeReference[1..1] } LogEntry .. NonEmptyString LogEntry .. Identifier LogEntry .. xs.string LogEntry .. Subject LogEntry .. Event LogEntry .. xs.dateTime LogEntry .. NodeReference class Node { + identifier : NodeReference[1..1] + name : NonEmptyString[1..1] + description : NonEmptyString[1..1] + baseURL : xs.anyURI[1..1] + services : Services[0..1] + synchronization : Synchronization[0..1] + nodeReplicationPolicy : NodeReplicationPolicy[0..1] + ping : Ping[0..1] + subject : Subject[0..*] + contactSubject : Subject[1..*] + replicate : xs.boolean[1.. 1] + synchronize : xs.boolean[1.. 1] + type : NodeType[1.. 1] + state : NodeState[1.. 1] } Node .. NodeReference Node .. NonEmptyString Node .. xs.anyURI Node .. Services Node .. Synchronization Node .. NodeReplicationPolicy Node .. Ping Node .. Subject Node .. xs.boolean Node .. NodeType Node .. NodeState class NodeReplicationPolicy { + maxObjectSize : xs.unsignedLong[0..1] + spaceAllocated : xs.unsignedLong[0..1] + allowedNode : NodeReference[0..*] + allowedObjectFormat : ObjectFormatIdentifier[0..*] } NodeReplicationPolicy .. xs.unsignedLong NodeReplicationPolicy .. NodeReference NodeReplicationPolicy .. ObjectFormatIdentifier class NodeList { + node : Node[1..*] } NodeList .. Node class NodeReference { } NodeReference --|> NonEmptyString class ObjectFormat { + formatId : ObjectFormatIdentifier[1..1] + formatName : xs.string[1..1] + formatType : xs.string[1..1] } ObjectFormat .. ObjectFormatIdentifier ObjectFormat .. xs.string class ObjectFormatList { + objectFormat : ObjectFormat[1..*] } ObjectFormatList .. ObjectFormat ObjectFormatList --|> Slice class ObjectInfo { + identifier : Identifier[1..1] + formatId : ObjectFormatIdentifier[1..1] + checksum : Checksum[1..1] + dateSysMetadataModified : xs.dateTime[1..1] + size : xs.unsignedLong[1..1] } ObjectInfo .. Identifier ObjectInfo .. ObjectFormatIdentifier ObjectInfo .. Checksum ObjectInfo .. xs.dateTime ObjectInfo .. xs.unsignedLong class ObjectList { + objectInfo : ObjectInfo[0..*] } ObjectList .. ObjectInfo ObjectList --|> Slice class ObjectLocation { + nodeIdentifier : NodeReference[1..1] + baseURL : xs.anyURI[1..1] + version : ServiceVersion[1..*] + url : xs.anyURI[1..1] + preference : xs.int[0..1] } ObjectLocation .. NodeReference ObjectLocation .. xs.anyURI ObjectLocation .. ServiceVersion ObjectLocation .. xs.int class ObjectLocationList { + identifier : Identifier[1..1] + objectLocation : ObjectLocation[0..*] } ObjectLocationList .. Identifier ObjectLocationList .. ObjectLocation class Person { + subject : Subject[1..1] + givenName : NonEmptyString[1..*] + familyName : NonEmptyString[1..1] + email : NonEmptyString[0..*] + isMemberOf : Subject[0..*] + equivalentIdentity : Subject[0..*] + verified : xs.boolean[0..1] } Person .. Subject Person .. NonEmptyString Person .. xs.boolean class Ping { + success : xs.boolean[0..1] + lastSuccess : xs.dateTime[0..1] } Ping .. xs.boolean Ping .. xs.dateTime class Replica { + replicaMemberNode : NodeReference[1..1] + replicationStatus : ReplicationStatus[1..1] + replicaVerified : xs.dateTime[1..1] } Replica .. NodeReference Replica .. ReplicationStatus Replica .. xs.dateTime class ReplicationPolicy { + preferredMemberNode : NodeReference[0..*] + blockedMemberNode : NodeReference[0..*] + replicationAllowed : xs.boolean[0.. 1] + numberReplicas : xs.int[0.. 1] } ReplicationPolicy .. NodeReference ReplicationPolicy .. xs.boolean ReplicationPolicy .. xs.int class Service { + restriction : ServiceMethodRestriction[0..*] + name : ServiceName[1.. 1] + version : ServiceVersion[1.. 1] + available : xs.boolean[0.. 1] } Service .. ServiceMethodRestriction Service .. ServiceName Service .. ServiceVersion Service .. xs.boolean class ServiceMethodRestriction { } ServiceMethodRestriction --|> SubjectList class Services { + service : Service[1..*] } Services .. Service class Session { + subject : Subject[1..1] + subjectInfo : SubjectInfo[0..1] } Session .. Subject Session .. SubjectInfo class Schedule { + hour : CrontabEntry[1..1] + mday : CrontabEntry[1..1] + min : CrontabEntry[1..1] + mon : CrontabEntry[1..1] + sec : CrontabEntrySeconds[1..1] + wday : CrontabEntry[1..1] + year : CrontabEntry[1..1] } Schedule .. CrontabEntry Schedule .. CrontabEntrySeconds class Slice { + count : xs.int[1..1] + start : xs.int[1..1] + total : xs.int[1..1] } Slice .. xs.int class Synchronization { + schedule : Schedule[1..1] + lastHarvested : xs.dateTime[0..1] + lastCompleteHarvest : xs.dateTime[0..1] } Synchronization .. Schedule Synchronization .. xs.dateTime class Subject { } Subject --|> NonEmptyString class SubjectInfo { + person : Person[0..*] + group : Group[0..*] } SubjectInfo .. Person SubjectInfo .. Group class SubjectList { + subject : Subject[0..*] } SubjectList .. Subject class SystemMetadata { + serialVersion : xs.unsignedLong[0..1] + identifier : Identifier[1..1] + formatId : ObjectFormatIdentifier[1..1] + size : xs.unsignedLong[1..1] + checksum : Checksum[1..1] + submitter : Subject[0..1] + rightsHolder : Subject[1..1] + accessPolicy : AccessPolicy[0..1] + replicationPolicy : ReplicationPolicy[0..1] + obsoletes : Identifier[0..1] + obsoletedBy : Identifier[0..1] + archived : xs.boolean[0..1] + dateUploaded : xs.dateTime[0..1] + dateSysMetadataModified : xs.dateTime[0..1] + originMemberNode : NodeReference[0..1] + authoritativeMemberNode : NodeReference[0..1] + replica : Replica[0..*] } SystemMetadata .. xs.unsignedLong SystemMetadata .. Identifier SystemMetadata .. ObjectFormatIdentifier SystemMetadata .. Checksum SystemMetadata .. Subject SystemMetadata .. AccessPolicy SystemMetadata .. ReplicationPolicy SystemMetadata .. xs.boolean SystemMetadata .. xs.dateTime SystemMetadata .. NodeReference SystemMetadata .. Replica @enduml .. include:: Types_include.txt .. ###### .. class:: ChecksumAlgorithm The cryptographic hash algorithm used to calculate a checksum. DataONE recognizes the Library of Congress list of cryptographic hash algorithms that can be used as names in this field, and specifically uses the *madsrdf:authoritativeLabel* field as the name of the algorithm in this field. See: `Library of Congress Cryptographic Algorithm Vocabulary`_. All compliant implementations must support at least SHA-1 and MD5, but may support other algorithms as well. Valid entries include: SHA-1, MD5 The default checksum is *SHA-1*. .. _Library of Congress Cryptographic Algorithm Vocabulary: http://id.loc.gov/vocabulary/cryptographicHashFunctions.rdf .. code-block:: xml .. image:: images/class_ChecksumAlgorithm.png .. @startuml images/class_ChecksumAlgorithm.png ChecksumAlgorithm --|> xs.string @enduml .. ###### .. class:: CrontabEntry A single value in the series of values that together form a single crontab entry. The format follows the syntax conventions defined by the `Quartz Scheduler`_, as excerpted here under the Apache 2 license: .. _Quartz Scheduler: http://www.quartz-scheduler.org/api/2.1.0/org/quartz/CronExpression.html .. include:: Types_crontabentry.txt .. code-block:: xml .. image:: images/class_CrontabEntry.png .. @startuml images/class_CrontabEntry.png CrontabEntry --|> xs.token @enduml .. ###### .. class:: CrontabEntrySeconds A restriction on the seconds field in a single Schedule entry, following the syntax conventions defined by the `Quartz Scheduler`_. The wildcard character value is not allowed in this (seconds) field as this would create an impractical synchronization schedule .. _Quartz Scheduler: http://www.quartz-scheduler.org/api/2.1.0/org/quartz/CronExpression.html .. code-block:: xml .. image:: images/class_CrontabEntrySeconds.png .. @startuml images/class_CrontabEntrySeconds.png CrontabEntrySeconds --|> xs.token @enduml .. ###### .. class:: Event The controlled list of events that are logged, which will include *create*, *update*, *delete*, *read*, *replicate*, *synchronization_failed* and *replication_failed* events. .. code-block:: xml .. image:: images/class_Event.png .. @startuml images/class_Event.png enum Event Event : create Event : read Event : update Event : delete Event : replicate Event : synchronization_failed Event : replication_failed @enduml .. ###### .. class:: NodeState An indicator of the current node accessibility. Nodes that are marked *down* are inaccessible for service operations, those that are *up* are in the normal accessible state, and *unknown* indicates that the state has not been determined yet. .. code-block:: xml .. image:: images/class_NodeState.png .. @startuml images/class_NodeState.png enum NodeState NodeState : up NodeState : down NodeState : unknown @enduml .. ###### .. class:: NodeType The type of this node, which is either *mn* for Member Nodes, or *cn* for Coordinating Nodes. .. code-block:: xml .. image:: images/class_NodeType.png .. @startuml images/class_NodeType.png enum NodeType NodeType : mn NodeType : cn NodeType : Monitor @enduml .. ###### .. class:: NonEmptyString A derived string type with at least length 1 and it must contain non-whitespace. .. code-block:: xml .. image:: images/class_NonEmptyString.png .. @startuml images/class_NonEmptyString.png NonEmptyString --|> xs.string @enduml .. ###### .. class:: ObjectFormatIdentifier A string used to identify an instance of :class:`Types.ObjectFormat` and MUST be unique within an instance of :class:`Types.ObjectFormatList`. .. code-block:: xml .. image:: images/class_ObjectFormatIdentifier.png .. @startuml images/class_ObjectFormatIdentifier.png ObjectFormatIdentifier --|> NonEmptyString @enduml .. ###### .. class:: NonEmptyString800 An NonEmptyString800 is a NonEmptyString string with a maximum length of 800 characters. .. code-block:: xml .. image:: images/class_NonEmptyString800.png .. @startuml images/class_NonEmptyString800.png NonEmptyString800 --|> NonEmptyString @enduml .. ###### .. class:: NonEmptyNoWhitespaceString800 A NonEmptyNoWhitespaceString800 is a NonEmptyString800 string that doesn't allow whitespace characters (space, tab, newline, carriage return). Unicode whitespace characters outside of the ASCII character set need to be checked programmatically. .. code-block:: xml .. image:: images/class_NonEmptyNoWhitespaceString800.png .. @startuml images/class_NonEmptyNoWhitespaceString800.png NonEmptyNoWhitespaceString800 --|> NonEmptyString800 @enduml .. ###### .. class:: Permission A string value indicating the set of actions that can be performed on a resource as specified in an access policy. The set of permissions include the ability to read a resource (*read*), modify a resource (*write*), and to change the set of access control policies for a resource (*changePermission*). Permission levels are cumulative, in that write permission implicitly grants read access, and changePermission permission implicitly grants write access (and therefore read as well). If a subject is granted multiple permissions, the highest level of access applies. .. code-block:: xml .. image:: images/class_Permission.png .. @startuml images/class_Permission.png enum Permission Permission : read Permission : write Permission : changePermission @enduml .. ###### .. class:: ReplicationStatus An enumerated string value indicating the current state of a replica of an object. When an object identified needs to be replicated, it is added to the replication task queue and is marked as *queued*; a CN will pick up that task and request that it be replicated to a MN and marks that it as *requested*; when a MN finishes replicating the object, it informs the CN that it is finished and it is marked as *completed*. If an MN is unable to complete replication, the replication status is marked as *failed*. Periodically a CN checks each replica to be sure it is both available and valid (matching checksum with original), and if it is either inaccessible or invalid then it marks it as *invalidated*, which indicates that the object replication needs to be invoked again. The replication process is described in Use Case 09 (:doc:`/design/UseCases/09_uc`). .. code-block:: xml .. image:: images/class_ReplicationStatus.png .. @startuml images/class_ReplicationStatus.png enum ReplicationStatus ReplicationStatus : queued ReplicationStatus : requested ReplicationStatus : completed ReplicationStatus : failed ReplicationStatus : invalidated @enduml .. ###### .. class:: ServiceName The name of a service that is available on a Node. .. code-block:: xml .. image:: images/class_ServiceName.png .. @startuml images/class_ServiceName.png ServiceName --|> NonEmptyString @enduml .. ###### .. class:: ServiceVersion The version of a service provided by a Node. Service versions are expressed as version labels such as "v1", "v2". DataONE services are released only as major service versions; patches to services are not indicated in this version label. .. code-block:: xml .. image:: images/class_ServiceVersion.png .. @startuml images/class_ServiceVersion.png ServiceVersion --|> NonEmptyString @enduml .. ###### .. class:: AccessPolicy A set of rules that specifies as a whole the allowable permissions that a given user, group, or system has for accessing a resource, including data, metadata, resource map, and service resources. An access policy consists of a sequence of allow rules that grant permissions to principals, which can be individual users, groups of users, symbolic users, or systems and services. .. attribute:: allow Type: :class:`Types.AccessRule` .. code-block:: xml .. image:: images/class_AccessPolicy.png .. @startuml images/class_AccessPolicy.png class AccessPolicy { + allow : AccessRule[1..*] } AccessPolicy .. AccessRule @enduml .. ###### .. class:: AccessRule A rule that is used to allow a :term:`subject` to perform an action (such as read or write) on an object in DataONE. Rules are tuples (subject, permission) specifying which permissions are allowed for the subjects(s). If a subject is granted multiple permissions, the highest level of access applies. The resource on which the access control rules are being applied is determined by the containing :term:`SystemMetadata` document, or in the case of methods such as :func:`CNAuthorization.setAccessPolicy`, by the :term:`pid` in the method parameters. Access control rules are specified by the :term:`Origin Member Node` when the object is first registered in DataONE. If no rules are specified at that time, then the object is deemed to be private and the only user with access to the object (read, write, or otherwise) is the :term:`Rights Holder`. .. attribute:: subject Type: :class:`Types.Subject` .. attribute:: permission Type: :class:`Types.Permission` .. code-block:: xml .. image:: images/class_AccessRule.png .. @startuml images/class_AccessRule.png class AccessRule { + subject : Subject[1..*] + permission : Permission[1..*] } AccessRule .. Subject AccessRule .. Permission @enduml .. ###### .. class:: Checksum Represents the value of a computed :term:`checksum` expressed as a hexadecimal formatted version of the message digest. Note that these hex values should be treated as case-insensitive strings, in that leading zeros must be preserved, and digests can use a mixture of upper and lower case letters to represent the hex values. Comparison algorithms MUST be able to handle any variant of these representations (e.g., by performing a case-insensitive string match on hex digests from the same algorithm). .. code-block:: xml .. image:: images/class_Checksum.png .. @startuml images/class_Checksum.png class Checksum { + algorithm : ChecksumAlgorithm } Checksum .. ChecksumAlgorithm Checksum --|> xs.string @enduml .. ###### .. class:: ChecksumAlgorithmList Represents a list of :term:`checksum` algorithms. .. attribute:: algorithm Type: :class:`Types.ChecksumAlgorithm` .. code-block:: xml .. image:: images/class_ChecksumAlgorithmList.png .. @startuml images/class_ChecksumAlgorithmList.png class ChecksumAlgorithmList { + algorithm : ChecksumAlgorithm[1..*] } ChecksumAlgorithmList .. ChecksumAlgorithm @enduml .. ###### .. class:: Group Group represents metadata about a :term:`Subject` that represents a collection of other Subjects. Groups provide a convenient mechanism to express access rules for certain roles that are not necessarily tied to particular :term:`principals` over time. .. attribute:: subject Type: :class:`Types.Subject` The unique, immutable identifier of the :term:`group`. Group subjects must not be reused, and so they are both immutable and can not be deleted from the DataONE system. .. attribute:: groupName Type: :class:`Types.NonEmptyString` The name of the Group. .. attribute:: hasMember Type: :class:`Types.Subject` A :term:`Subject` that is a member of this group, expressed using the unique identifier for that Subject. .. attribute:: rightsHolder Type: :class:`Types.Subject` Represents the list of owners of this :term:`group`. All groups are readable by anyone in the DataONE system, but can only be modified by subjects listed in *rightsHolder* fields. Designation as a :term:`rightsHolder` allows the subject, or their equivalent identities, to make changes to the mutable properties of the group, including its name, membership list and rights holder list. The subject of the group itself is immutable. .. code-block:: xml .. image:: images/class_Group.png .. @startuml images/class_Group.png class Group { + subject : Subject[1..1] + groupName : NonEmptyString[1..1] + hasMember : Subject[0..*] + rightsHolder : Subject[1..*] } Group .. Subject Group .. NonEmptyString @enduml .. ###### .. class:: Identifier An :term:`identifier` (:term:`PID`) in the DataONE system that is used to uniquely and globally identify an object. Identifiers can not be reused once assigned. Identifiers can not be deleted from the DataONE system.Identifiers are represented by a Unicode string of printable characters, excluding :term:`whitespace`. All representations of identifiers must be encoded in 7-bit ASCII or UTF-8. Identifiers have a maximum length of 800 characters, and a variety of other properties designed for preservation and longevity. Some discussion on this is described in the `PID documentation`_ and in decision `ticket 577`_. .. _ticket 577: https://redmine.dataone.org/issues/577 .. _PID documentation: http://mule1.dataone.org/ArchitectureDocs-current/design/PIDs.html .. code-block:: xml .. image:: images/class_Identifier.png .. @startuml images/class_Identifier.png class Identifier { } Identifier --|> NonEmptyNoWhitespaceString800 @enduml .. ###### .. class:: Log Represents a collection of :class:`Types.LogEntry` elements, used to transfer log information between DataONE components. .. code-block:: xml .. image:: images/class_Log.png .. @startuml images/class_Log.png class Log { + logEntry : LogEntry[0..*] } Log .. LogEntry Log --|> Slice @enduml .. ###### .. class:: LogEntry A single log entry as reported by a Member Node or Coordinating Node through the :func:`MNCore.getLogRecords` or :func:`CNCore.getLogRecords` methods. .. attribute:: entryId Type: :class:`Types.NonEmptyString` A unique identifier for this log entry. The identifier should be unique for a particular node; This is not drawn from the same value space as other identifiers in DataONE, and so is not subjec to the same restrictions. .. attribute:: identifier Type: :class:`Types.Identifier` The :term:`identifier` of the object that was the target of the operation which generated this log entry. .. attribute:: ipAddress Type: :class:`Types.xs.string` The IP address, as reported by the service receiving the request, of the request origin. .. attribute:: userAgent Type: :class:`Types.xs.string` The user agent of the client making the request, as reported in the User-Agent HTTP header. .. attribute:: subject Type: :class:`Types.Subject` The :term:`Subject` used for making the request. This may be the DataONE :term:`public` user if the request is not authenticated, otherwise it will be the *Subject* of the certificate used for authenticating the request. .. attribute:: event Type: :class:`Types.Event` An entry from the :class:`Types.Event` enumeration indicating the type of operation that triggered the log message. .. attribute:: dateLogged Type: :class:`Types.xs.dateTime` A :class:`Types.DateTime` time stamp indicating when the event triggering the log message ocurred. Note that all time stamps in DataONE are in UTC. .. attribute:: nodeIdentifier Type: :class:`Types.NodeReference` The unique identifier for the node where the log message was generated. .. code-block:: xml .. image:: images/class_LogEntry.png .. @startuml images/class_LogEntry.png class LogEntry { + entryId : NonEmptyString[1..1] + identifier : Identifier[1..1] + ipAddress : xs.string[1..1] + userAgent : xs.string[1..1] + subject : Subject[1..1] + event : Event[1..1] + dateLogged : xs.dateTime[1..1] + nodeIdentifier : NodeReference[1..1] } LogEntry .. NonEmptyString LogEntry .. Identifier LogEntry .. xs.string LogEntry .. Subject LogEntry .. Event LogEntry .. xs.dateTime LogEntry .. NodeReference @enduml .. ###### .. class:: Node A set of values that describe a member or coordinating node, its Internet location, and the services it supports. Several nodes may exist on a single physical device or hostname. .. attribute:: identifier Type: :class:`Types.NodeReference` A unique identifier for the node of the form ``urn:node:NODEID`` where NODEID is the node specific identifier. This value MUST NOT change for future implementations of the same node, whereas the *baseURL* may change in the future. .. attribute:: name Type: :class:`Types.NonEmptyString` A human readable name of the Node. This name can be used as a label in many systems to represent the node, and thus should be short, but understandable. .. attribute:: description Type: :class:`Types.NonEmptyString` Description of a Node, explaining the community it serves and other relevant information about the node, such as what content is maintained by this node and any other free style notes. .. attribute:: baseURL Type: :class:`Types.xs.anyURI` The base URL of the node, indicating the protocol, fully qualified domain name, and path to the implementing service, excluding the version of the API. e.g. ``https://server.example.edu/app/d1/mn`` rather than ``https://server.example.edu/app/d1/mn/v1`` .. attribute:: services Type: :class:`Types.Services` A list of services that are provided by this node. Used in node descriptions so that nodes can provide metadata about each service they implement and support. .. attribute:: synchronization Type: :class:`Types.Synchronization` Configuration information for the process by which content is harvested from Member Nodes to Coordinating Nodes. This includes the schedule on which harvesting should occur, and metadata about the last synchronization attempts for the node. .. attribute:: nodeReplicationPolicy Type: :class:`Types.NodeReplicationPolicy` The replication policy for this node that expresses constraints on object size, total objects, source nodes, and object format types. A node may want to restrict replication from only certain peer nodes, may have file size limits, total allocated size limits, or may want to focus on being a replica target for domain-specific object formats. .. attribute:: ping Type: :class:`Types.Ping` Stored results from the :func:`MNCore.ping` and :func:`CNCore.ping` methods. .. attribute:: subject Type: :class:`Types.Subject` The :term:`Subject` of this node, which can be repeated as needed. The *Node.subject* represents the identifier of the node that would be found in X.509 certificates used to securely communicate with this node. Thus, it is an :term:`X.509 Distinguished Name` that applies to the host on which the Node is operating. When (and if) this hostname changes the new subject for the node would be added to the Node to track the subject that has been used in various access control rules over time. .. attribute:: contactSubject Type: :class:`Types.Subject` The appropriate person or group to contact regarding the disposition, management, and status of this Member Node. The *Node.contactSubject* is an :term:`X.509 Distinguished Name` for a person or group that can be used to look up current contact details (e.g., name, email address) for the contact in the DataONE Identity service. DataONE uses the *contactSubject* to provide notices of interest to DataONE nodes, including information such as policy changes, maintenance updates, node outage notifications, among other information useful for administering a node. Each node that is registered with DataONE must provide at least one *contactSubject* that has been :term:`verified` with DataONE. .. attribute:: replicate Type: :class:`Types.xs.boolean` Set to *true* if the node is willing to be a :term:`replication target`, otherwise *false*. .. attribute:: synchronize Type: :class:`Types.xs.boolean` Set to *true* if the node should be :term:`synchronized` by a Coordinating Node, otherwise *false*. .. attribute:: type Type: :class:`Types.NodeType` The type of the node (Coordinating, Member), chosen from the :class:`Types.NodeType` type. .. attribute:: state Type: :class:`Types.NodeState` The state of the node (*up*, *down*), chosen from the :class:`Types.NodeState` type. .. code-block:: xml .. image:: images/class_Node.png .. @startuml images/class_Node.png class Node { + identifier : NodeReference[1..1] + name : NonEmptyString[1..1] + description : NonEmptyString[1..1] + baseURL : xs.anyURI[1..1] + services : Services[0..1] + synchronization : Synchronization[0..1] + nodeReplicationPolicy : NodeReplicationPolicy[0..1] + ping : Ping[0..1] + subject : Subject[0..*] + contactSubject : Subject[1..*] + replicate : xs.boolean[1.. 1] + synchronize : xs.boolean[1.. 1] + type : NodeType[1.. 1] + state : NodeState[1.. 1] } Node .. NodeReference Node .. NonEmptyString Node .. xs.anyURI Node .. Services Node .. Synchronization Node .. NodeReplicationPolicy Node .. Ping Node .. Subject Node .. xs.boolean Node .. NodeType Node .. NodeState @enduml .. ###### .. class:: NodeReplicationPolicy The overall replication policy for the node that expresses constraints on object size, total objects, source nodes, and object format types. A node may choose to restrict replication from only certain peer nodes, may have file size limits, total allocated size limits, or may want to focus on being a :term:`replication target` for domain-specific object formats. .. attribute:: maxObjectSize Type: :class:`Types.xs.unsignedLong` An optional statement of the maximum size in octets (8-bit bytes) of objects this node is willing to accept for replication. .. attribute:: spaceAllocated Type: :class:`Types.xs.unsignedLong` An optional statement of the total space in bytes allocated for replication object storage on this node. .. attribute:: allowedNode Type: :class:`Types.NodeReference` An optional, repeatable statement of a peer source node from which this node is willing to replicate content, expressed as a :class:`Types.NodeReference`. .. attribute:: allowedObjectFormat Type: :class:`Types.ObjectFormatIdentifier` An optional, repeatable statement of an object format that this node is willing to replicate, expressed as a :class:`Types.ObjectFormatIdentifier`. .. code-block:: xml .. image:: images/class_NodeReplicationPolicy.png .. @startuml images/class_NodeReplicationPolicy.png class NodeReplicationPolicy { + maxObjectSize : xs.unsignedLong[0..1] + spaceAllocated : xs.unsignedLong[0..1] + allowedNode : NodeReference[0..*] + allowedObjectFormat : ObjectFormatIdentifier[0..*] } NodeReplicationPolicy .. xs.unsignedLong NodeReplicationPolicy .. NodeReference NodeReplicationPolicy .. ObjectFormatIdentifier @enduml .. ###### .. class:: NodeList A list of :class:`Types.Node` entries returned by :func:`CNCore.listNodes()`. NodeList is described in :mod:`NodeList`. .. attribute:: node Type: :class:`Types.Node` .. code-block:: xml .. image:: images/class_NodeList.png .. @startuml images/class_NodeList.png class NodeList { + node : Node[1..*] } NodeList .. Node @enduml .. ###### .. class:: NodeReference A unique identifier for a DataONE Node. The *NodeReference* must be unique across nodes, and must always be assigned to one Member or Coordinating Node instance even in the event of the *BaseURL* or other characteristics changing. .. code-block:: xml .. image:: images/class_NodeReference.png .. @startuml images/class_NodeReference.png class NodeReference { } NodeReference --|> NonEmptyString @enduml .. ###### .. class:: ObjectFormat One value from the DataONE Object Format Vocabulary which is returned by :func:`CNCore.getFormat()`. An *ObjectFormat* is the structure returned from the :func:`CNCore.getFormat()` method of the CN REST interface. It provides the unique identifier and the name associated with the object format. Future versions may contain additional structured content from external common typing systems. .. attribute:: formatId Type: :class:`Types.ObjectFormatIdentifier` The unique identifier of the object format in the DataONE Object Format Vocabulary. The identifier should comply with DataONE Identifier rules, i.e. no whitespace, only UTF-8 or US-ASCII printable characters. .. attribute:: formatName Type: :class:`Types.xs.string` For objects that are typed using a Document Type Definition, this lists the well-known and accepted named version of the DTD. In other cases, an appropriately unambiguous descriptive name should be chosen. .. attribute:: formatType Type: :class:`Types.xs.string` A string field indicating whether or not this format is :term:`science data` (*DATA*), :term:`science metadata` (*METADATA*) or a :term:`resource map` (*RESOURCE*). If the format is a self-describing data format that includes science metadata, then the field should also be set to science metadata. .. code-block:: xml .. image:: images/class_ObjectFormat.png .. @startuml images/class_ObjectFormat.png class ObjectFormat { + formatId : ObjectFormatIdentifier[1..1] + formatName : xs.string[1..1] + formatType : xs.string[1..1] } ObjectFormat .. ObjectFormatIdentifier ObjectFormat .. xs.string @enduml .. ###### .. class:: ObjectFormatList An ObjectFormatList is the structure returned from the :func:`CNCore.listFormats()` method of the CN REST interface. It provides a list of named object formats defined in the DataONE system. Each :class:`Types.ObjectFormat` returned in the list describes the object format via its name, and future versions may contain additional structured content from common external typing systems. .. code-block:: xml .. image:: images/class_ObjectFormatList.png .. @startuml images/class_ObjectFormatList.png class ObjectFormatList { + objectFormat : ObjectFormat[1..*] } ObjectFormatList .. ObjectFormat ObjectFormatList --|> Slice @enduml .. ###### .. class:: ObjectInfo Metadata about an object, representing a subset of the metadata found in :class:`Types.SystemMetadata`. .. attribute:: identifier Type: :class:`Types.Identifier` .. attribute:: formatId Type: :class:`Types.ObjectFormatIdentifier` .. attribute:: checksum Type: :class:`Types.Checksum` .. attribute:: dateSysMetadataModified Type: :class:`Types.xs.dateTime` .. attribute:: size Type: :class:`Types.xs.unsignedLong` .. code-block:: xml .. image:: images/class_ObjectInfo.png .. @startuml images/class_ObjectInfo.png class ObjectInfo { + identifier : Identifier[1..1] + formatId : ObjectFormatIdentifier[1..1] + checksum : Checksum[1..1] + dateSysMetadataModified : xs.dateTime[1..1] + size : xs.unsignedLong[1..1] } ObjectInfo .. Identifier ObjectInfo .. ObjectFormatIdentifier ObjectInfo .. Checksum ObjectInfo .. xs.dateTime ObjectInfo .. xs.unsignedLong @enduml .. ###### .. class:: ObjectList A list of object locations (nodes) from which the object can be retrieved. .. code-block:: xml .. image:: images/class_ObjectList.png .. @startuml images/class_ObjectList.png class ObjectList { + objectInfo : ObjectInfo[0..*] } ObjectList .. ObjectInfo ObjectList --|> Slice @enduml .. ###### .. class:: ObjectLocation Portion of an :class:`Types.ObjectLocationList` indicating the node from which the object can be retrieved. The principal information on each location is found in the *nodeIdentifier*, all other fields are provided for convenience, but could also be looked up from the :class:`Types.NodeList` information obtained from :func:`CNCore.listNodes`. .. attribute:: nodeIdentifier Type: :class:`Types.NodeReference` Identifier of the :class:`Types.Node` (the same identifier used in the node registry for identifying the node). .. attribute:: baseURL Type: :class:`Types.xs.anyURI` The current base URL (the *baseURL* element from the :class:`Types.Node` record) for services implemented on the target node. Used with service version to construct a URL for service calls to this node. Note that complete information on services available on a Node is available from the :func:`CNCore.listNodes` service. .. attribute:: version Type: :class:`Types.ServiceVersion` The version of services implemented on the node. Used with base url to construct a URL for service calls to this node. Note that complete information on services available on a Node is available from the :func:`CNCore.listNodes` service. .. attribute:: url Type: :class:`Types.xs.anyURI` The full (absolute) URL that can be used to retrieve the object using the get() method of the rest interface. For example, if identifier was "ABX154", and the node had a base URL of ``http://mn1.dataone.org/mn`` then the value would be ``http://mn1.dataone.org/mn/v1/object/ABX154`` .. attribute:: preference Type: :class:`Types.xs.int` A weighting parameter that provides a hint to the caller for the relative preference for nodes from which the content should be retrieved. Higher values have higher preference. .. code-block:: xml .. image:: images/class_ObjectLocation.png .. @startuml images/class_ObjectLocation.png class ObjectLocation { + nodeIdentifier : NodeReference[1..1] + baseURL : xs.anyURI[1..1] + version : ServiceVersion[1..*] + url : xs.anyURI[1..1] + preference : xs.int[0..1] } ObjectLocation .. NodeReference ObjectLocation .. xs.anyURI ObjectLocation .. ServiceVersion ObjectLocation .. xs.int @enduml .. ###### .. class:: ObjectLocationList An *ObjectLocationList* is the structure returned from the :func:`CNRead.resolve` method of the CN REST interface. It provides a list of locations from which the specified object can be retrieved. .. attribute:: identifier Type: :class:`Types.Identifier` The :term:`identifier` of the object being resolved. .. attribute:: objectLocation Type: :class:`Types.ObjectLocation` List of nodes from which the object can be retrieved .. code-block:: xml .. image:: images/class_ObjectLocationList.png .. @startuml images/class_ObjectLocationList.png class ObjectLocationList { + identifier : Identifier[1..1] + objectLocation : ObjectLocation[0..*] } ObjectLocationList .. Identifier ObjectLocationList .. ObjectLocation @enduml .. ###### .. class:: Person *Person* represents metadata about a :term:`Principal` that is a person and that can be used by clients and nodes for :class:`Types.AccessPolicy` information. The mutable properties of a *Person* instance can only be changed by itself (i.e., the Subject identifying the Person instance) and by the Coordinating Node identity, but can be read by any identity in the DataONE system. .. attribute:: subject Type: :class:`Types.Subject` The unique, immutable identifier for the *Person*. .. attribute:: givenName Type: :class:`Types.NonEmptyString` The given name of the *Person*, repeatable if they have more than one given name. .. attribute:: familyName Type: :class:`Types.NonEmptyString` The family name of the *Person*. .. attribute:: email Type: :class:`Types.NonEmptyString` The email address of the *Person*, repeatable if they have more than one email address. .. attribute:: isMemberOf Type: :class:`Types.Subject` A *group* or role in which the *Person* is a member, expressed using the unique :class:`Types.Subject` identifier for that :class:`Types.Group`, and repeatable if they are a member of more than one group. .. attribute:: equivalentIdentity Type: :class:`Types.Subject` An alternative but equivalent identity for the :term:`principal` that has been used in alternate identity systems, repeatable if more than one equivalent identity applies. .. attribute:: verified Type: :class:`Types.xs.boolean` *true* if the name and email address of the *Person* have been :term:`verified` to ensure that the *givenName* and *familyName* represent the real person's legal name, and that the email address is correct for that person and is in the control of the indicated individual. Verification occurs through an established procedure within DataONE as part of the Identity Management system. A Person can not change their own *verified* field, but rather must be verified and changed through this DataONE established process. .. code-block:: xml .. image:: images/class_Person.png .. @startuml images/class_Person.png class Person { + subject : Subject[1..1] + givenName : NonEmptyString[1..*] + familyName : NonEmptyString[1..1] + email : NonEmptyString[0..*] + isMemberOf : Subject[0..*] + equivalentIdentity : Subject[0..*] + verified : xs.boolean[0..1] } Person .. Subject Person .. NonEmptyString Person .. xs.boolean @enduml .. ###### .. class:: Ping Store results from the :func:`MNCore.ping` method. .. attribute:: success Type: :class:`Types.xs.boolean` A boolean flag indicating *true* if the node was reached by the last :func:`MNCore.ping` or :func:`CNCore.ping` call, otherwise *false*. .. attribute:: lastSuccess Type: :class:`Types.xs.dateTime` The date time value (UTC) of the last time a successful ping was performed. .. code-block:: xml .. image:: images/class_Ping.png .. @startuml images/class_Ping.png class Ping { + success : xs.boolean[0..1] + lastSuccess : xs.dateTime[0..1] } Ping .. xs.boolean Ping .. xs.dateTime @enduml .. ###### .. class:: Replica Replica information that describes the existence of a replica of some object managed by the DataONE infrastructure, and its status. .. attribute:: replicaMemberNode Type: :class:`Types.NodeReference` A reference to the Member Node that houses this replica, regardless of whether it has arrived at the Member Node or not. See *replicationStatus* to determine if the replica is completely transferred. .. attribute:: replicationStatus Type: :class:`Types.ReplicationStatus` The current status of this replica, indicating the stage of replication process for the object. Only *completed* replicas should be considered as available. .. attribute:: replicaVerified Type: :class:`Types.xs.dateTime` The last date and time on which the integrity of a replica was verified by the coordinating node. Verification occurs by checking that the checksum of the stored object matches the checksum recorded for the object in the system metadata. .. code-block:: xml .. image:: images/class_Replica.png .. @startuml images/class_Replica.png class Replica { + replicaMemberNode : NodeReference[1..1] + replicationStatus : ReplicationStatus[1..1] + replicaVerified : xs.dateTime[1..1] } Replica .. NodeReference Replica .. ReplicationStatus Replica .. xs.dateTime @enduml .. ###### .. class:: ReplicationPolicy The *ReplicationPolicy* for an object defines if replication should be attempted for this object, and if so, how many replicas should be maintained. It also permits specification of preferred and blocked nodes as potential replication targets. .. attribute:: preferredMemberNode Type: :class:`Types.NodeReference` Preferred Nodes are utilized over other nodes as replication targets, up to the number of replicas requested. If preferred nodes are unavailable, or if insufficient nodes are listed as preferred to meet the requested number of replicas, then the Coordinating Nodes will pick additional replica nodes for the content. .. attribute:: blockedMemberNode Type: :class:`Types.NodeReference` The object MUST never be replicated to nodes listed as *blockedMemberNodes*. Where there is a conflict between a *preferredMemberNode* and a *blockedMemberNode* entry, the *blockedMemberNode* entry prevails. .. attribute:: replicationAllowed Type: :class:`Types.xs.boolean` A boolean flag indicating if the object should be replicated (*true*, default) or not (*false*). .. attribute:: numberReplicas Type: :class:`Types.xs.int` An integer indicating the number of replicas targeted for this object. Defaults to 3. .. code-block:: xml .. image:: images/class_ReplicationPolicy.png .. @startuml images/class_ReplicationPolicy.png class ReplicationPolicy { + preferredMemberNode : NodeReference[0..*] + blockedMemberNode : NodeReference[0..*] + replicationAllowed : xs.boolean[0.. 1] + numberReplicas : xs.int[0.. 1] } ReplicationPolicy .. NodeReference ReplicationPolicy .. xs.boolean ReplicationPolicy .. xs.int @enduml .. ###### .. class:: Service The available Dataone Service APIs that are exposed on a Node. Without a restriction, all service methods are available to all callers. Restrictions may be placed on individual methods of the service to limit the service to a certain set of :term:`Subjects`. Enforcement of these service restrictions is incumbent on the Node service implementation. .. attribute:: restriction Type: :class:`Types.ServiceMethodRestriction` A list of method names and :term:`Subjects` with permission to invoke those methods. .. attribute:: name Type: :class:`Types.ServiceName` The name of the service. The valid list of entries for Member Nodes includes: *MNCore*, *MNRead*, *MNAuthorization*, *MNStorage*, and *MNReplication*. The valid list of entries for Coordinating Nodes includes: *CNCore*, *CNRead*, *CNAuthorization*, *CNIdentity*, *CNReplication*, and *CNRegister*. .. attribute:: version Type: :class:`Types.ServiceVersion` Version of the service supported by the node. Version is expressed in whole steps, no minor version identifiers are used. For example, the version 1.0.0 API would be indicated by the value "v1" .. attribute:: available Type: :class:`Types.xs.boolean` A boolean flag indicating if the service is available (*true*, default) or otherwise (*false*). .. code-block:: xml .. image:: images/class_Service.png .. @startuml images/class_Service.png class Service { + restriction : ServiceMethodRestriction[0..*] + name : ServiceName[1.. 1] + version : ServiceVersion[1.. 1] + available : xs.boolean[0.. 1] } Service .. ServiceMethodRestriction Service .. ServiceName Service .. ServiceVersion Service .. xs.boolean @enduml .. ###### .. class:: ServiceMethodRestriction Describes an optional restriction policy for a given method. If this element exists for a service method, its use is restricted, and only :term:`Subjects` listed in the list are allowed to invoke the method named in the *methodName* attribute. .. code-block:: xml .. image:: images/class_ServiceMethodRestriction.png .. @startuml images/class_ServiceMethodRestriction.png class ServiceMethodRestriction { } ServiceMethodRestriction --|> SubjectList @enduml .. ###### .. class:: Services A list of services that are provided by a node. Used in Node descriptions so that Nodes can provide metadata about each service they implement and support. .. attribute:: service Type: :class:`Types.Service` .. code-block:: xml .. image:: images/class_Services.png .. @startuml images/class_Services.png class Services { + service : Service[1..*] } Services .. Service @enduml .. ###### .. class:: Session Information about the authenticated session for a service transaction. Session data is retrieved from the SSL client certificate and populated in the *Session* object. The subject represents the person or system that authenticated successfully, and the *subjectInfo* contains a listing of alternate identities (both Persons and Groups) that are also valid identities for this user. The *subjectInfo* should include at least one :class:`Types.Person` or :class:`Types.Group` entry that provides the attributes of the subject that was authenticated. .. attribute:: subject Type: :class:`Types.Subject` .. attribute:: subjectInfo Type: :class:`Types.SubjectInfo` .. code-block:: xml .. image:: images/class_Session.png .. @startuml images/class_Session.png class Session { + subject : Subject[1..1] + subjectInfo : SubjectInfo[0..1] } Session .. Subject Session .. SubjectInfo @enduml .. ###### .. class:: Schedule The schedule on which :term:`synchronization` will run for a particular node. Syntax for each time slot follows the syntax conventions defined by the Quartz Scheduler (http://www.quartz-scheduler.org/api/2.1.0/org/quartz/CronExpression.html) .. attribute:: hour Type: :class:`Types.CrontabEntry` .. attribute:: mday Type: :class:`Types.CrontabEntry` .. attribute:: min Type: :class:`Types.CrontabEntry` .. attribute:: mon Type: :class:`Types.CrontabEntry` .. attribute:: sec Type: :class:`Types.CrontabEntrySeconds` .. attribute:: wday Type: :class:`Types.CrontabEntry` .. attribute:: year Type: :class:`Types.CrontabEntry` .. code-block:: xml .. image:: images/class_Schedule.png .. @startuml images/class_Schedule.png class Schedule { + hour : CrontabEntry[1..1] + mday : CrontabEntry[1..1] + min : CrontabEntry[1..1] + mon : CrontabEntry[1..1] + sec : CrontabEntrySeconds[1..1] + wday : CrontabEntry[1..1] + year : CrontabEntry[1..1] } Schedule .. CrontabEntry Schedule .. CrontabEntrySeconds @enduml .. ###### .. class:: Slice An abstract type used as a common base for other types that need to include *count*, *start*, and *total* attributes to indicate which slice of a list is represented by a set of records. The first element in a list is always index 0, i.e. list indexes are zero-based. .. attribute:: count Type: :class:`Types.xs.int` The number of entries in the slice. .. attribute:: start Type: :class:`Types.xs.int` The zero-based index of the first element in the slice. .. attribute:: total Type: :class:`Types.xs.int` The total number of entries in the source list from which the slice was extracted. .. code-block:: xml .. image:: images/class_Slice.png .. @startuml images/class_Slice.png class Slice { + count : xs.int[1..1] + start : xs.int[1..1] + total : xs.int[1..1] } Slice .. xs.int @enduml .. ###### .. class:: Synchronization Configuration information for the process by which metadata is harvested from Member Nodes to Coordinating Nodes, including the schedule on which harvesting should occur, and information about the last :term:`synchronization` attempts for the node. Member Nodes providing *Synchronization* information only need to provide the *schedule*. Coordinating Nodes must set values for the *lastHarvested* and *lastCompleteHarvest* fields. .. attribute:: schedule Type: :class:`Types.Schedule` An entry set by the Member Node indicating the frequency for which synchronization should occur. This setting will be influenced by the frequency with which content is updated on the Member Node and the acceptable latency for detection and subsequent processing of new content. .. attribute:: lastHarvested Type: :class:`Types.xs.dateTime` The most recent modification date (UTC) of objects checked during the last harvest of the node. .. attribute:: lastCompleteHarvest Type: :class:`Types.xs.dateTime` The last time (UTC) all the data from a node was pulled from a member node during a complete synchronization process. .. code-block:: xml .. image:: images/class_Synchronization.png .. @startuml images/class_Synchronization.png class Synchronization { + schedule : Schedule[1..1] + lastHarvested : xs.dateTime[0..1] + lastCompleteHarvest : xs.dateTime[0..1] } Synchronization .. Schedule Synchronization .. xs.dateTime @enduml .. ###### .. class:: Subject An identifier for a Person (user), Group, Organization, or System. The :term:`Subject` is a string that provides a formal name to identify a user or group in the DataONE Identity Management Service. The *subject* is represented by a unique, persistent, non-reassignable identifier string that follows the same constraints as :class:`Types.Identifier`. Subjects are immutable and can not be deleted. .. code-block:: xml .. image:: images/class_Subject.png .. @startuml images/class_Subject.png class Subject { } Subject --|> NonEmptyString @enduml .. ###### .. class:: SubjectInfo A list of :term:`Subjects`, including both :class:`Types.Person` and :class:`Types.Group` entries returned from the :func:`CNIdentity.getSubjectInfo` service and :func:`CNIdentity.listSubjects` services. .. attribute:: person Type: :class:`Types.Person` .. attribute:: group Type: :class:`Types.Group` .. code-block:: xml .. image:: images/class_SubjectInfo.png .. @startuml images/class_SubjectInfo.png class SubjectInfo { + person : Person[0..*] + group : Group[0..*] } SubjectInfo .. Person SubjectInfo .. Group @enduml .. ###### .. class:: SubjectList A list of :term:`Subjects` used for identity/group management .. attribute:: subject Type: :class:`Types.Subject` .. code-block:: xml .. image:: images/class_SubjectList.png .. @startuml images/class_SubjectList.png class SubjectList { + subject : Subject[0..*] } SubjectList .. Subject @enduml .. ###### .. class:: 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 objects such as science data, science metadata, and resource map objects and the relationships between objects (e.g. *obsoletes* and *obsoletedBy*). The information is maintained dynamically by Coordinating Nodes and is mutable in that it reflects 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. 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. .. attribute:: serialVersion Type: :class:`Types.xs.unsignedLong` A serial number maintained by the coordinating node to indicate when changes have occurred to *SystemMetadata* to avoid update conflicts. Clients should ensure that they have the most recent version of a *SystemMetadata* document before attempting to update, otherwise an error will be thrown to prevent conflicts. The Coordinating Node must set this optional field when it receives the system metadata document. .. attribute:: identifier Type: :class:`Types.Identifier` The :term:`identifier` is a unique Unicode string that is used to canonically name and identify the object in DataONE. Each object in DataONE is immutable, and therefore all objects must have a unique Identifier. If two objects are related to one another (such as one object is a more recent version of another object), each of these two objects will have unique identifiers. The relationship among the objects is specified in other metadata fields (see *Obsoletes* and *ObsoletedBy*), but this does not preclude the inclusion of version information in the identifier string. However, DataONE treats all Identifiers as opaque and will not try to infer versioning semantics based on the content of the Identifiers -- rather, this information is found in the *Obsoletes* and *ObsoletedBy* fields. Note that identifiers are used in a number of REST API calls as parts of the URL path. As such, all special characters such as "/", " ", "+", "\", "%" must be properly encoded, e.g. "%2F", "%20", "%2B", "%5C", "%25" respectively when used in REST method calls. See RFC3896_ for more details. For example, the :func:`MNRead.get()` call for an object with identifier: ``http://some.location.name/mydata.cgi?id=2088`` would be: ``http://mn1.server.name/mn/v1/object/http:%2F%2Fsome.location.name%2Fmydata.cgi%3Fid%3D2088`` .. _RFC3896: http://www.ietf.org/rfc/rfc3896.txt .. attribute:: formatId Type: :class:`Types.ObjectFormatIdentifier` Designation of the standard or format that should be used to interpret the contents of the object, drawn from controlled list of formats that are provided by the DataONE :class:`Types.ObjectFormat` service. DataONE maintains a list of formats in use and their canonical FormatIdentifiers. The format identifier for an object should imply its mime type for data objects and metadata type and serialization format for metadata objects. Examples include the namespace of the EML 2.1 metadata specification, the DOCTYPE of the Biological Data Profile, the mime type of ``text/csv`` files, and the canonical name of the NetCDF specification. .. attribute:: size Type: :class:`Types.xs.unsignedLong` The size of the object in octets (8-bit bytes). .. attribute:: checksum Type: :class:`Types.Checksum` A calculated hash value used to validate object integrity over time and after network transfers. The value is calculated using a standard hashing algorithm that is accepted by DataONE and that is indicated in the included *ChecksumAlgorithm* attribute. .. attribute:: submitter Type: :class:`Types.Subject` :term:`Subject` who submitted the associated abject to the DataONE Member Node. The Member Node must set this field when it receives the system metadata document from a client (the field is optional from the client perspective, but is required when a MN creates an object). By default, the submitter lacks any rights to modify an object, so care must be taken to set *rightsHolder* and *accessPolicy* correctly with a reference to the subject of the submitter if the submitter is to be able to make further changes to the object. .. attribute:: rightsHolder Type: :class:`Types.Subject` :term:`Subject` that has ultimate authority for the object and is authorized to make all decisions regarding the disposition and accessibility of the object. The *rightsHolder* has all rights to access the object, update the object, and grant permissions for the object, even if additional access control rules are not specified for the object. Typically, the *rightsHolder* field would be set to the name of the subject submitting an object, so that the person can make further changes later. By default, the *submitter* lacks any rights to modify an object, so care must be taken to set *rightsHolder* and *accessPolicy* correctly with a reference to the subject of the *submitter* if the *submitter* is to be able to make further changes to the object. .. attribute:: accessPolicy Type: :class:`Types.AccessPolicy` The *accessPolicy* determines which :term:`Subjects` are allowed to make changes to an object in addition to the *rightsHolder* and *authoritativeMemberNode*. The *accessPolicy* is set for an object during a :func:`MNStorage.create` or :func:`MNStorage.update` call, or when *SystemMetadata* is updated on the Coordinating Node via various mechanisms. This policy replaces any existing policies that might exist for the object. Member Nodes that house an object are obligated to enforce the *accessPolicy* for that object. .. attribute:: replicationPolicy Type: :class:`Types.ReplicationPolicy` A controlled list of policy choices that determine how many replicas should be maintained for a given object and any preferences or requirements as to which Member Nodes should be allowed to house the replicas. The policy determines whether replication is allowed, the number of replicas desired, the list of preferred nodes to hold the replicas, and a list of blocked nodes on which replicas must not exist. .. attribute:: obsoletes Type: :class:`Types.Identifier` The :term:`Identifier` of an object that is a prior version of the object described in this system metadata record and that is obsoleted by this object. When an object is obsoleted, it is removed from all DataONE search indices but is still accessible from the :func:`CNRead.get` service. .. attribute:: obsoletedBy Type: :class:`Types.Identifier` The :term:`Identifier` of an object that is a subsequent version of the object described in this system metadata record and that therefore obsoletes this object. When an object is obsoleted, it is removed from all DataONE search indices but is still accessible from the :func:`CNRead.get` service. .. attribute:: archived Type: :class:`Types.xs.boolean` A boolean flag, set to *true* if the object has been classified as archived. An archived object does not show up in search indexes in DataONE, but is still accessible via the CNRead and MNRead services if associated access polices allow. The field is optional, and if absent, then objects are implied to not be archived, which is the same as setting archived to *false*. .. attribute:: dateUploaded Type: :class:`Types.xs.dateTime` Date and time (UTC) that the object was uploaded into the DataONE system, which is typically the time that the object is first created on a Member Node using the :func:`MNStorage.create` operation. Note this is independent of the publication or release date of the object. The Member Node must set this optional field when it receives the system metadata document from a client. .. attribute:: dateSysMetadataModified Type: :class:`Types.xs.dateTime` Date and time (UTC) that this system metadata record was last modified in the DataONE system. This is the same timestamp as *dateUploaded* until the system metadata is further modified. The Member Node must set this optional field when it receives the system metadata document from a client. .. attribute:: originMemberNode Type: :class:`Types.NodeReference` A reference to the Member Node that originally uploaded the associated object. This value should never change, even if the Member Node ceases to exist. .. attribute:: authoritativeMemberNode Type: :class:`Types.NodeReference` A reference to the Member Node that acts as the authoritative source for an object in the system. The *authoritativeMemberNode* will often also be the *originMemberNode*, unless there has been a need to transfer authority for an object to a new node, such as when a Member Node becomes defunct. The *authoritativeMemberNode* has all the rights of the *rightsHolder* to maintain and curate the object, including making any changes necessary. .. attribute:: replica Type: :class:`Types.Replica` A container field used to repeatedly provide several metadata fields about each replica that exists in the system, or is being replicated. Note that a *replica* field exists even for the Authoritative/Origin Member Nodes so that the status of those objects can be tracked. .. code-block:: xml .. image:: images/class_SystemMetadata.png .. @startuml images/class_SystemMetadata.png class SystemMetadata { + serialVersion : xs.unsignedLong[0..1] + identifier : Identifier[1..1] + formatId : ObjectFormatIdentifier[1..1] + size : xs.unsignedLong[1..1] + checksum : Checksum[1..1] + submitter : Subject[0..1] + rightsHolder : Subject[1..1] + accessPolicy : AccessPolicy[0..1] + replicationPolicy : ReplicationPolicy[0..1] + obsoletes : Identifier[0..1] + obsoletedBy : Identifier[0..1] + archived : xs.boolean[0..1] + dateUploaded : xs.dateTime[0..1] + dateSysMetadataModified : xs.dateTime[0..1] + originMemberNode : NodeReference[0..1] + authoritativeMemberNode : NodeReference[0..1] + replica : Replica[0..*] } SystemMetadata .. xs.unsignedLong SystemMetadata .. Identifier SystemMetadata .. ObjectFormatIdentifier SystemMetadata .. Checksum SystemMetadata .. Subject SystemMetadata .. AccessPolicy SystemMetadata .. ReplicationPolicy SystemMetadata .. xs.boolean SystemMetadata .. xs.dateTime SystemMetadata .. NodeReference SystemMetadata .. Replica @enduml