|
| 1 | +======================= |
| 2 | +Metadata Export Formats |
| 3 | +======================= |
| 4 | + |
| 5 | +.. contents:: |toctitle| |
| 6 | + :local: |
| 7 | + |
| 8 | +Introduction |
| 9 | +------------ |
| 10 | + |
| 11 | +Dataverse ships with a number of metadata export formats available for published datasets. A given metadata export |
| 12 | +format may be available for user download (via the UI and API) and/or be available for use in Harvesting between |
| 13 | +Dataverse instances. |
| 14 | + |
| 15 | +As of v5.14, Dataverse provides a mechanism for third-party developers to create new metadata Exporters than implement |
| 16 | +new metadata formats or that replace existing formats. All the necessary dependencies are packaged in an interface JAR file |
| 17 | +available from Maven Central. Developers can distribute their new Exporters as JAR files which can be dynamically loaded |
| 18 | +into Dataverse instances - see :ref:`external-exporters`. Developers are encouraged to make their Exporter code available |
| 19 | +via https://github.com/gdcc/dataverse-exporters (or minimally, to list their existence in the README there). |
| 20 | + |
| 21 | +Exporter Basics |
| 22 | +--------------- |
| 23 | + |
| 24 | +New Exports must implement the ``io.gdcc.spi.export.Exporter`` interface. The interface includes a few methods for the Exporter |
| 25 | +to provide Dataverse with the format it produces, a display name, format mimetype, and whether the format is for download |
| 26 | +and/or harvesting use, etc. It also includes a main ``exportDataset(ExportDataProvider dataProvider, OutputStream outputStream)`` |
| 27 | +method through which the Exporter receives metadata about the given dataset (via the ``ExportDataProvider``, described further |
| 28 | +below) and writes its output (as an OutputStream). |
| 29 | + |
| 30 | +Exporters that create an XML format must implement the ``io.gdcc.spi.export.XMLExporter`` interface (which extends the Exporter |
| 31 | +interface). XMLExporter adds a few methods through which the XMLExporter provides information to Dataverse about the XML |
| 32 | +namespace and version being used. |
| 33 | + |
| 34 | +Exporters also need to use the ``@AutoService(Exporter.class)`` which makes the class discoverable as an Exporter implementation. |
| 35 | + |
| 36 | +The ``ExportDataProvider`` interface provides several methods through which your Exporter can receive dataset and file metadata |
| 37 | +in various formats. Your exporter would parse the information in one or more of these inputs to retrieve the values needed to |
| 38 | +generate the Exporter's output format. |
| 39 | + |
| 40 | +The most important methods/input formats are: |
| 41 | + |
| 42 | +- ``getDatasetJson()`` - metadata in the internal Dataverse JSON format used in the native API and available via the built-in JSON metadata export. |
| 43 | +- ``getDatasetORE()`` - metadata in the OAI_ORE format available as a built-in metadata format and as used in Dataverse's BagIT-based Archiving capability. |
| 44 | +- ``getDatasetFileDetails`` - detailed file-level metadata for ingested tabular files. |
| 45 | + |
| 46 | +The first two of these provide ~complete metadata about the dataset along with the metadata common to all files. This includes all metadata |
| 47 | +entries from all metadata blocks, PIDs, tags, Licenses and custom terms, etc. Almost all built-in exporters today use the JSON input. |
| 48 | +The newer OAI_ORE export, which is JSON-LD-based, provides a flatter structure and references metadata terms by their external vocabulary ids |
| 49 | +(e.g. http://purl.org/dc/terms/title) which may make it a prefereable starting point in some cases. |
| 50 | + |
| 51 | +The last method above provides a new JSON-formatted serialization of the variable-level file metadata Dataverse generates during ingest of tabular files. |
| 52 | +This information has only been included in the built-in DDI export, as the content of a ``dataDscr`` element. (Hence inspecting the edu.harvard.iq.dataverse.export.DDIExporter and related classes would be a good way to explore how the JSON is structured.) |
| 53 | + |
| 54 | +The interface also provides |
| 55 | + |
| 56 | +- ``getDatasetSchemaDotOrg();`` and |
| 57 | +- ``getDataCiteXml();``. |
| 58 | + |
| 59 | +These provide subsets of metadata in the indicated formats. They may be useful starting points if your exporter will, for example, only add one or two additional fields to the given format. |
| 60 | + |
| 61 | +If an Exporter cannot create a requested metadata format for some reason, it should throw an ``io.gdcc.spi.export.ExportException``. |
| 62 | + |
| 63 | +Building an Exporter |
| 64 | +-------------------- |
| 65 | + |
| 66 | +The example at https://github.com/gdcc/dataverse-exporters provides a Maven pom.xml file suitable for building an Exporter JAR file and that repository provides additional development guidance. |
| 67 | + |
| 68 | +There are four dependencies needed to build an Exporter: |
| 69 | + |
| 70 | +- ``io.gdcc dataverse-spi`` library containing the interfaces discussed above and the ExportException class |
| 71 | +- ``com.google.auto.service auto-service``, which provides the @AutoService annotation |
| 72 | +- ``jakarta.json jakarata.json-api`` for JSON classes |
| 73 | +- ``jakarta.ws.rs jakarta.ws.rs-api``, which provides a MediaType enumeration for specifying mime types. |
| 74 | + |
| 75 | +Specifying a Prerequisite Export |
| 76 | +-------------------------------- |
| 77 | + |
| 78 | +An advanced feature of the Exporter mechanism allows a new Exporter to specify that it requires, as input, |
| 79 | +the output of another Exporter. An example of this is the builting HTMLExporter which requires the output |
| 80 | +of the DDI XML Exporter to produce an HTML document with the same DDI content. |
| 81 | + |
| 82 | +This is configured by providing the metadata format name via the ``Exporter.getPrerequisiteFormatName()`` method. |
| 83 | +When this method returns a non-empty format name, Dataverse will provide the requested format to the Exporter via |
| 84 | +the ``ExportDataProvider.getPrerequisiteInputStream()`` method. |
| 85 | + |
| 86 | +Developers and administrators deploying Exporters using this mechanism should be aware that, since metadata formats |
| 87 | +can be changed by other Exporters, the InputStream received may not hold the expected metadata. Developers should clearly |
| 88 | +document their compatability with the built-in or third-party Exporters they support as prerequisites. |
0 commit comments