PRIMRE Developer Documents
PRIMRE and Database Integrations
The Portal and Repository for Information on Marine Renewable Energy (PRIMRE) provides centralized access, standardization, community building, and integration of marine energy data repositories and knowledge hubs. Rather than creating a single repository to host all content, the idea is to create an ecosystem of databases that interact and share information in intuitive ways. This provides value from integration, such as reducing redundancy and improving discoverability, while allowing each database the flexibility to meet the specific needs of their sponsors and users.
Integration can range from reciprocal links to federation of metadata. Reciprocal links can positively influence search engine rankings for both databases and can provide a positive user experience for navigating to other authoritative information. Federation of metadata is where data or information catalogs are shared between databases using API interfaces. This provides greater data discoverability and leads to positive changes such as terminology consistency and the application of data standards.
PRIMRE integrates seven knowledge hubs funded by the U.S. Department of Energy Water Power Technologies Office (WPTO) which are managed by the National Renewable Energy Laboratory (NREL), Pacific Northwest National Laboratory (PNNL), and Sandia National Laboratories (Sandia). Each of these knowledge hubs maintains unique identities and purposes, but content is integrated into a centralized PRIMRE search. The PRIMRE team welcomes data integrations with other relevant marine energy databases, including those from other countries. This page is meant to provide guidance on integrations by detailing terminology consistency, metadata standards, and the metadata federation process.
Table 1. PRIMRE Knowledge Hubs
| PRIMRE Knowledge Hubs | Location | Purpose |
| MHK Data Repository | https://mhkdr.openei.org/ | Data from WPTO-funded projects |
| Tethys | https://tethys.pnnl.gov/ | Documents on environmental effects |
| Tethys Engineering | https://tethys-engineering.pnnl.gov/ | Technical documents. |
| Marine Energy Software | https://software.primre.org/ | Software |
| Telesto | https://primre.org/Telesto | Information on marine energy development |
| Marine Energy Projects Database | https://primre.org/Databases/Projects_Database | Project and device information |
| Marine Energy Atlas | https://maps.nrel.gov/marine-energy-atlas/ | GIS-based resource maps |
Terminology Consistency
Achieving standardization of metadata tags, categories, and terminology used to describe marine energy information is a key goal for PRIMRE. Standardization will enable users to find the data they seek, wherever it is located within PRIMRE and associated repositories and knowledge bases — the PRIMRE universe. These standards describe metadata needed for each site to expose information to search engines, such as Google, and to ensure that the appropriate content is displayed in relevant searches. This practice is commonly referred to as Search Engine Optimization (SEO) and increases the likelihood of successful searches (i.e., discoverability); thus, driving marine energy community members to PRIMRE and the resources they need. The adoption of these standards will also facilitate connections between disparate sites via federation of metadata that will improve cross-site search capabilities.
Rather than create another set of terminology, PRIMRE is drawing from international standards such as the International Electrotechnical Commission Technical Committee 114 (IEC TC 114) and guidelines and practices from the International Energy Agency’s Ocean Energy Systems (IEA OES) tasks. PRIMRE is also drawing from terminology in literature, as reflected in the PRIMRE glossary, Tethys glossary and Tethys Engineering glossary.
Controlled Taxonomies
There are several taxonomies that the PRIMRE team controls, as they become key filters in the centralized search. These include content type, technology, and tags. Tags are only optionally controlled, as only a curated list of terms are provided as filters on the PRIMRE centralized search. If another repository uses alternative terminology, they will need to be mapped to the PRIMRE taxonomies to facilitate integration after the metadata federation. A list of terms is provided in the metadata schema below.
Dates
The collection and storage of dates are critical metadata for knowledge hubs, many of which have adopted their own definitions for key dates, including date received, date revised, date accepted, date originated, date available, date published, project start date, project end date, and more. Different sites may collect different subsets of these dates, or different dates entirely, as necessary to categorize their information. Complicating matters, different sites often have different concepts of what one or more of these dates actually mean, creating inconsistency. To avoid confusion, each knowledge hub should be clear about the definition of their metadata terms and the type of data being reported.
In order to simplify the PRIMRE Metadata Schema and consolidate to only the bare minimum needed to share information across sites, the PRIMRE Metadata Schema only requires two dates: the origination date, used to determine how new the data or information are; and the modified date, used to determine how new the metadata record for the data or information are. Origination date is an abstract concept meant to capture the critical creation date for all types of information, whether created, collected, instrumented, or published (as may be the case in a paper or journal article). Modified date is the most recent date the metadata record for this information was changed or updated and is intended to notify other sites sharing this information that they have been updated and should be included in a response to any request to pull in the latest information.
Publisher
The PRIMRE Metadata Schema has been designed to encapsulate all types of information, from data to code to publications, from a variety of knowledge hubs. Each of these may have a different concept of a publisher. For some sites, a publisher might be the organization responsible for releasing the information to the public or the originating organization, for others it might be a more traditional publisher such as a scientific journal, magazine, or report.
For this reason, publisher has been omitted from the PRIMRE Metadata Schema, which only requires one or more authors and a source organization.
Sites adopting the PRIMRE Metadata Schema are encouraged to use the definition of publisher most appropriate for their site. For example, classic document types like journal articles and books are encouraged to use the established publisher, while sites containing grey literature, data, code, or any media lacking a formal publisher are encouraged to use the originating organization (i.e., report by Sandia National Laboratories).
PRIMRE Metadata Schema
Most websites categorize content using custom metadata schemas, often composed of common elements such as tags or keywords. These schemas vary from site to site, preserving the unique scope of each database. Individual knowledge hubs should continue to have their own information categorization and classification schemas, especially to describe the unique properties of their content. However, maintaining consistency across several main categories will create an opportunity to map across knowledge hubs. The PRIMRE team has worked to synchronize the classification of standard data and information package terms, as well as basic MRE technology terms, as the highest level of categorization on the knowledge hubs. The resulting metadata schema is intended to be comprehensive, yet not too specific, using established terminology based on the best available literature, building upon proven schemas (e.g., DCAT and Project Open Data). It is recommended that other databases in the marine energy field, whether new or existing, follow the PRIMRE metadata schema described below.
By incorporating the PRIMRE metadata schema into their classification, these knowledge hubs can more easily synchronize with PRIMRE and any other sites adopting the same classification, now and in the future. By creating consistency among metadata fields, knowledge hubs can more easily integrate with other sites in the PRIMRE community, and their content can be more easily organized to make it discoverable and familiar to users.
The PRIMRE metadata classification is a living schema managed by the PRIMRE community. As technologies are innovated or as new information becomes available, the schema will be reviewed and updated as necessary.
The table below details the metadata schema used by sites within the PRIMRE community to support interoperability with each other and to register their assets in the centralized PRIMRE search. Only publicly available metadata should be provided to PRIMRE. The recommended format is as a JSON endpoint with a modifiedDate filter so updates are less computationally intensive.
The following are examples where the PRIMRE API has already been created:
- MHKDR: https://mhkdr.openei.org/api?action=getSubmissionsForPRIMRE&modifiedDate=2025-01-01
- Tethys: https://tethys.pnnl.gov/api/primre_export?modifiedDate=2025-01-01
- Tethys Engineering: https://tethys-engineering.pnnl.gov/api/primre_export?modifiedDate=2025-01-01
- Marine Energy Software: https://software.primre.org/api/softwares
| Field | Definition | Required |
| URI | The primary, unique identifier that represents the content on your site. Also a permanent, resolvable web address leading directly to the content.
|
yes |
| type | Overarching category to describe the content (e.g., Dataset, Document). Type should be provided as an array of Strings. These categories are controlled and managed by PRIMRE.
|
yes |
| landingPage | Optional URL providing access to the human-friendly hub or landing page for the content that users can be directed to for all resources tied to the content. This URL should exist on the database being connected to PRIMRE. This field is not intended for an agency's homepage (e.g. www.energy.gov). Any content behind a paywall or other accessibility barrier is required to have a publicly accessible landing page.
|
no |
| sourceURL | URL providing access to the original source, if the source differs from the entry on the database.
|
no |
| title | Human-readable name of the asset. (e.g. title of a conference paper). Should be in plain English and include sufficient detail to describe the contents of the asset. Avoid the use of internal language or acronyms not commonly understood.
|
yes |
| description | Human-readable description (or abstract) with sufficient detail to describe the contents of the asset in a way that enables users of the asset to quickly understand the contents and nuances of the asset. No character limit. Avoid HTML markup. | yes |
| author | Name of the individual(s) who created or contributed to the content. Authors should be provided as an array of Strings.
|
yes |
| organization | The non-person entity or entities responsible for the creation of the content. This is often not the entity funding the creation of the content. Organizations should be provided as an array of Strings.
|
no |
| originationDate | The date the content was originally created, derived, or collected. Dates should be provided in year, month, day. Time is not necessary.
All dates and times should be in UTC timezone.
|
yes |
| spatial | The range of spatial applicability of the content. At least one spatial extent is required, based on GeoJSON specifications. Extents can be a point, multipoint, or a bounding box. Points are specified by a coordinate pair ("coordinates") and bounding boxes are specific using two points, the Northeast corner and the Southwest corner. See examples below:
spatial->point->coords spatial->boundingBox->[NE coords, SW coords]
Example (multipoint):
Example (bounding box):
|
yes |
| technologyType | A list of marine renewable energy technology types. Values should be provided as an array of Strings. These categories are controlled and managed by PRIMRE.
|
no |
| tags | A curated list of terms and/or keywords used to describe the content. Content can be associated with multiple values. Consistency of tags between databases will aid in the discoverability of content. Tags should be provided as an array of Strings.
|
yes |
| signatureProject | A list of marine renewable energy projects funded by DOE's Water Power Technologies Office that are being highlighted to make project outputs more discoverable. Values should be provided as an array of Strings. These categories are controlled and managed by PRIMRE.
|
No |
| modifiedDate | Most recent date and time on which the content or any of the metadata were changed, updated, or modified. Meant to inform which content should be pulled.
All dates and times should be in the UTC timezone.
|
yes |
Federating Content Between Databases
Adoption of the PRIMRE metadata standards described above allows any organization in the marine energy community to join with the PRIMRE universe by (1) displaying their information within the centralized PRIMRE search or (2) ingesting content from other databases into their own results.
Relevant marine energy databases that create a JSON API as described above will be ingested into the PRIMRE centralized search alongside content from other connected databases. Prior to building an API, database developers are recommended to confirm that the content is relevant to PRIMRE, map content to PRIMRE terminology, and verify that there are discrete links to each content. These links can point to a unique landing page for the content or a single result for the content in a search or map.
Other databases may also prefer to display federated content from a PRIMRE database into their own database. When a user enters a search term, results from federated websites may appear alongside content for the current site, or results may appear in a separate tab with direct links to the origin. Each PRIMRE API has a modifiedDate parameter that filters the API to only display content either added or modified from a specific date, allowing an ingest script to run on a schedule and only add the newest content. Once the catalog is ingested, it may be displayed however the database sees fit. Some examples of this include:
- Tethys searches return results from Tethys Engineering and MHKDR, though results are shown on separate tabs so as to not dilute the search of Tethys content.
Acknowledgements
PRIMRE is a multi-laboratory project carried out by a team of researchers from Sandia National Laboratories (Sandia), Pacific Northwest National Laboratory (PNNL), and the National Renewable Energy Laboratory (NREL), supported through funding by the US Department of Energy (DOE) Water Power Technologies Office (WPTO). The PRIMRE guidelines and best practices document was developed by the PRIMRE multi-laboratory team.
If you have any questions about database federation or wish to learn more, please contact us.
