.. WARNING! This file is automatically generated. Edits will be lost. Data Types in CICore -------------------- .. module:: v2_0.Types :synopsis: Catalog of data types (structures) used by the DataONE cicore. **Versions** * :doc:`Version 1.0` * :doc:`Version 1.1` * :doc:`Version 2.0` **Quick Reference** - :class:`v2_0.Types.Log` - :class:`v2_0.Types.LogEntry` - :class:`v2_0.Types.MediaType` - :class:`v2_0.Types.MediaTypeProperty` - :class:`v2_0.Types.Node` - :class:`v2_0.Types.NodeList` - :class:`v2_0.Types.ObjectFormat` - :class:`v2_0.Types.ObjectFormatList` - :class:`v2_0.Types.OptionList` - :class:`v2_0.Types.Property` - :class:`v2_0.Types.SystemMetadata` .. image:: images/v2_0.classes_combined.png .. @startuml images/v2_0.classes_combined.png class v2_0.MediaTypeProperty { + name : xs.string } v2_0.MediaTypeProperty .. xs.string v2_0.MediaTypeProperty --|> xs.string class v2_0.MediaType { + property : v2_0.MediaTypeProperty[0..*] + name : xs.string[1.. 1] } v2_0.MediaType .. v2_0.MediaTypeProperty v2_0.MediaType .. xs.string class v2_0.SystemMetadata { + seriesId : Identifier[0..1] + mediaType : v2_0.MediaType[0..1] + fileName : xs.string[0..1] } v2_0.SystemMetadata .. Identifier v2_0.SystemMetadata .. v2_0.MediaType v2_0.SystemMetadata .. xs.string v2_0.SystemMetadata --|> SystemMetadata class v2_0.NodeList { + node : v2_0.Node[1..*] } v2_0.NodeList .. v2_0.Node class v2_0.Node { + property : v2_0.Property[0..*] } v2_0.Node .. v2_0.Property v2_0.Node --|> Node class v2_0.Property { + key : xs.string + type : xs.string } v2_0.Property .. xs.string v2_0.Property .. xs.string v2_0.Property --|> xs.string class v2_0.ObjectFormat { + mediaType : v2_0.MediaType[0..1] + extension : xs.string[0..1] } v2_0.ObjectFormat .. v2_0.MediaType v2_0.ObjectFormat .. xs.string v2_0.ObjectFormat --|> ObjectFormat class v2_0.ObjectFormatList { + objectFormat : v2_0.ObjectFormat[1..*] } v2_0.ObjectFormatList .. v2_0.ObjectFormat v2_0.ObjectFormatList --|> Slice class v2_0.Log { + logEntry : v2_0.LogEntry[0..*] } v2_0.Log .. v2_0.LogEntry v2_0.Log --|> Slice class v2_0.LogEntry { + entryId : NonEmptyString[1..1] + identifier : Identifier[1..1] + ipAddress : xs.string[1..1] + userAgent : xs.string[1..1] + subject : Subject[1..1] + event : NonEmptyString[1..1] + dateLogged : xs.dateTime[1..1] + nodeIdentifier : NodeReference[1..1] } v2_0.LogEntry .. NonEmptyString v2_0.LogEntry .. Identifier v2_0.LogEntry .. xs.string v2_0.LogEntry .. Subject v2_0.LogEntry .. xs.dateTime v2_0.LogEntry .. NodeReference class v2_0.OptionList { + option : NonEmptyString[0..*] + key : xs.string[1.. 1] + description : xs.string[1.. 1] } v2_0.OptionList .. NonEmptyString v2_0.OptionList .. xs.string @enduml .. ###### .. class:: MediaTypeProperty Additional optional properties for MediaType as described by IANA. .. code-block:: xml .. image:: images/class_v2_0.MediaTypeProperty.png .. @startuml images/class_v2_0.MediaTypeProperty.png class v2_0.MediaTypeProperty { + name : xs.string } v2_0.MediaTypeProperty .. xs.string v2_0.MediaTypeProperty --|> xs.string @enduml .. ###### .. class:: MediaType Value drawn from the value space of IANA Media Types ( http://www.iana.org/assignments/media-types/media-types.xhtml ). When specified, indicates the IANA Media Type (aka MIME-Type) of the object. The name attribute MUST include the media type and subtype (e.g. text/csv). The media type value is not case sensitive. Any required media type parameters must be provided, and optional parameters may be specified. There are no explicit constraints on the name of media-type properties or their values, however they SHOULD conform to media type optional and required parameters as specified in the respective media type RFC. .. attribute:: property Type: :class:`v2_0.Types.MediaTypeProperty` Media-type parameter(s) as specified by the respective RFC for the media-type. .. attribute:: name Type: `xs.string`_ The value of the media-type specified as a required 'name' attribute of the mediaType element. .. code-block:: xml .. image:: images/class_v2_0.MediaType.png .. @startuml images/class_v2_0.MediaType.png class v2_0.MediaType { + property : v2_0.MediaTypeProperty[0..*] + name : xs.string[1.. 1] } v2_0.MediaType .. v2_0.MediaTypeProperty v2_0.MediaType .. xs.string @enduml .. ###### .. class:: SystemMetadata Extends :class:`Types.SystemMetadata` System metadata in DataONE APIs version 2.0 extends the :class:`types.SystemMetadata` definition of version 1.x by adding :term:`seriesId`, :term:`mediaType`, and :term:`fileName` elements. Each of these are optional, so Version 1.x System Metadata is compatible with Version 2.x, though not vice-versa. .. attribute:: seriesId Type: :class:`Types.Identifier` The :term:`seriesId` is an optional, unique Unicode string that identifies an object revision chain. A seriesId will resolve to the latest version of an object. A seriesId can not appear in any other revision chain. The values used for seriesId must be unique within DataONE and cannot be the same as the :term:`primary identifier` of an object. The same encoding rules used for identifier values apply to seriesId values. .. attribute:: mediaType Type: :class:`v2_0.Types.MediaType` When specified, indicates the IANA Media Type (aka MIME-Type) of the object. When specified, this value overrides the default value specified in the version 2.0 ObjectFormat structure. The value should include the media type and subtype (e.g. text/csv). The mediaType value is not case sensitive. The purpose of this value is to provide more detailed information about the specific media type of the associated object than may be available through the associated ObjectFormat. When specified, the mediaType value here overrides the value recorded in the referenced :class:`ObjectFormat`. This value SHOULD be set by the content creator. It MAY be set by any receiving agent if the value is not already set, the value in the ObjectFormat is less specific, and a correct value is specified elsewhere such as by a HTTP Content-Type parameter. This value MAY be changed to correct an erroneous entry. .. attribute:: fileName Type: `xs.string`_ Optional though recommended value providing a suggested file name for the object. Values should conform to cross platform file naming conventions. This value SHOULD be set by the content creator. This value MAY be set by any receiving agent Changing the value is discouraged once set, unless by the authoritative Member Node of content owner. .. code-block:: xml .. image:: images/class_v2_0.SystemMetadata.png .. @startuml images/class_v2_0.SystemMetadata.png class v2_0.SystemMetadata { + seriesId : Identifier[0..1] + mediaType : v2_0.MediaType[0..1] + fileName : xs.string[0..1] } v2_0.SystemMetadata .. Identifier v2_0.SystemMetadata .. v2_0.MediaType v2_0.SystemMetadata .. xs.string v2_0.SystemMetadata --|> SystemMetadata @enduml .. ###### .. class:: NodeList A list of :class:`v2_0.Types.Node` entries returned by :func:`CNCore.listNodes()`. NodeList is described in :mod:`NodeList`. .. attribute:: node Type: :class:`v2_0.Types.Node` .. code-block:: xml .. image:: images/class_v2_0.NodeList.png .. @startuml images/class_v2_0.NodeList.png class v2_0.NodeList { + node : v2_0.Node[1..*] } v2_0.NodeList .. v2_0.Node @enduml .. ###### .. class:: Node Extends :class:`Types.Node` Extends the Version 1.x :class:`Types.Node` by adding an optional unbounded parameter entry providing additional simple metadata relevant to a Node. .. attribute:: property Type: :class:`v2_0.Types.Property` Allows additional attributes be added to the Node document as needed. .. code-block:: xml .. image:: images/class_v2_0.Node.png .. @startuml images/class_v2_0.Node.png class v2_0.Node { + property : v2_0.Property[0..*] } v2_0.Node .. v2_0.Property v2_0.Node --|> Node @enduml .. ###### .. class:: Property Additional Property elements can be included to describe the Node in more detail. Some properties will come from controlled vocabularies indicated by the type attribute, while others will be free-form key value pairs. .. code-block:: xml .. image:: images/class_v2_0.Property.png .. @startuml images/class_v2_0.Property.png class v2_0.Property { + key : xs.string + type : xs.string } v2_0.Property .. xs.string v2_0.Property .. xs.string v2_0.Property --|> xs.string @enduml .. ###### .. class:: ObjectFormat Extends :class:`Types.ObjectFormat` Extends Version 1.x :class:`Types.ObjectFormat` by adding :term:`mediaType` and :term:`extension` elements. .. attribute:: mediaType Type: :class:`v2_0.Types.MediaType` The IANA Media Type for this object format. .. attribute:: extension Type: `xs.string`_ Suggested file name extension to be used when serializing this type of object to a file. The value should not include the period (.). .. code-block:: xml .. image:: images/class_v2_0.ObjectFormat.png .. @startuml images/class_v2_0.ObjectFormat.png class v2_0.ObjectFormat { + mediaType : v2_0.MediaType[0..1] + extension : xs.string[0..1] } v2_0.ObjectFormat .. v2_0.MediaType v2_0.ObjectFormat .. xs.string v2_0.ObjectFormat --|> ObjectFormat @enduml .. ###### .. class:: ObjectFormatList Extends :class:`Types.Slice` Extends :class:`Types.ObjectFormatList` to provide a list of :class:`v2_0.Types.ObjectFormat`. .. attribute:: objectFormat Type: :class:`v2_0.Types.ObjectFormat` .. code-block:: xml .. image:: images/class_v2_0.ObjectFormatList.png .. @startuml images/class_v2_0.ObjectFormatList.png class v2_0.ObjectFormatList { + objectFormat : v2_0.ObjectFormat[1..*] } v2_0.ObjectFormatList .. v2_0.ObjectFormat v2_0.ObjectFormatList --|> Slice @enduml .. ###### .. class:: Log Extends :class:`Types.Slice` Extends :class:`Types.Log` to represent a collection of :class:`v2_0.Types.LogEntry` elements, used to transfer log information between DataONE components. .. attribute:: logEntry Type: :class:`v2_0.Types.LogEntry` .. code-block:: xml .. image:: images/class_v2_0.Log.png .. @startuml images/class_v2_0.Log.png class v2_0.Log { + logEntry : v2_0.LogEntry[0..*] } v2_0.Log .. v2_0.LogEntry v2_0.Log --|> Slice @enduml .. ###### .. class:: LogEntry Extends :class:`Types.LogEntry` by relaxing the value space for the *event* element. .. 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 subject 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: `xs.string`_ The IP address, as reported by the service receiving the request, of the request origin. .. attribute:: userAgent Type: `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.NonEmptyString` A non-empty string indicating the type of event logged. A value from the :class:`Types.Event` enumeration is recommended though no longer required for Version 2.x. .. attribute:: dateLogged Type: `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_v2_0.LogEntry.png .. @startuml images/class_v2_0.LogEntry.png class v2_0.LogEntry { + entryId : NonEmptyString[1..1] + identifier : Identifier[1..1] + ipAddress : xs.string[1..1] + userAgent : xs.string[1..1] + subject : Subject[1..1] + event : NonEmptyString[1..1] + dateLogged : xs.dateTime[1..1] + nodeIdentifier : NodeReference[1..1] } v2_0.LogEntry .. NonEmptyString v2_0.LogEntry .. Identifier v2_0.LogEntry .. xs.string v2_0.LogEntry .. Subject v2_0.LogEntry .. xs.dateTime v2_0.LogEntry .. NodeReference @enduml .. ###### .. class:: OptionList A list of options that indicate the possible values for a DataONE service. Each option that can be validly sent to a service is listed, providing the specific key that should be used when interacting with the service, as well as a description of that key that allows API users to understand the usage of the key. For example, an OptionList might contain a list of themes that can be used with the MNView.view service, or for other services that have a configurable but controlled set of parameters. .. attribute:: option Type: :class:`Types.NonEmptyString` The key to be used within an API call to a DataONE service, including a description of the key and its impact on the service. For example, a key 'default' can be provided as the theme for the MNView.view service. Keys must not contain characters that will need to be URL escaped. .. attribute:: key Type: `xs.string`_ A value that can be used with a DataONE service. Key values must not contain any characters that need to be URL escaped, and should be short and informative. .. attribute:: description Type: `xs.string`_ The description of an option, indicating its intended use and impact on a DataONE service invocation. .. code-block:: xml .. image:: images/class_v2_0.OptionList.png .. @startuml images/class_v2_0.OptionList.png class v2_0.OptionList { + option : NonEmptyString[0..*] + key : xs.string[1.. 1] + description : xs.string[1.. 1] } v2_0.OptionList .. NonEmptyString v2_0.OptionList .. xs.string @enduml .. #### .. _xs.string: http://www.w3.org/TR/xmlschema-2/#string .. _xs.boolean: http://www.w3.org/TR/xmlschema-2/#boolean .. _xs.dateTime: http://www.w3.org/TR/xmlschema-2/#dateTime .. _xs.unsignedLong: http://www.w3.org/TR/xmlschema-2/#unsignedLong .. _xs.token: http://www.w3.org/TR/xmlschema-2/#token .. _xs.int: http://www.w3.org/TR/xmlschema-2/#int .. _xs.anyURI: http://www.w3.org/TR/xmlschema-2/#anyURI