+The PR should be directed: `base: develop` <- `compare: feature-1-collaboration`.
+The `PR title` describes the problem you have solved.
+Fill the PR template: +- Summary of the discussion +- Type of change (CHANGELOG.md) +- Workflow checklist + +Add `close #issueNumber` to [automatically close](https://help.github.com/en/github/managing-your-work-on-github/closing-issues-using-keywords) the corresponding issue.
+Assign a `Reviewer` or GitHub team.
+Assign yourself as `Assignee`
+Add suitable GitHub `Labels`
+Link the corresponding issue in `Development`
+`Create draft pull request`
+ +#### 4.1. Update the Changelog +Update comment of PR with `#PullRequestNumber`
+Add to the corresponding sections in `CHANGELOG.md`
+Commit and push changelog
+ +#### 4.2. Update the Documentation +Update the documentation
+Commit and push documentation
+ +#### 4.3. Convert draft to Pull Request +Check `Ready for review` + +#### 4.4. Let someone else review your PR +Follow the GitHub guide [approving a pull request with required reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews).
+Assign one reviewer or a user group and get into contact. + +If you are the reviewer: +- Check the changes in all corresponding files. +- Checkout the branch and run code. +- Comment if you would like to change something (Use `Request changes`) +- If all tests pass and all changes are good, `Approve` the PR. +- Leave a comment and some nice words! + +#### 4.1. Merge the PR +Follow the GitHub guide [merging a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). + +#### 4.2. Delete the feature branch +Follow the GitHub guide [deleting a branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch). + +### 5. Close the issue +Document the result in a few sentences and close the issue.
+Check that all steps have been documented: + +- Issue title describes the problem you solved? +- All commit messages are linked in the issue? +- The branch was deleted? +- Entry in CHANGELOG.md? +- PR is closed? +- Issue is closed? diff --git a/LICENSE b/LICENSE.txt similarity index 100% rename from LICENSE rename to LICENSE.txt diff --git a/README.md b/README.md deleted file mode 100644 index 017549a4..00000000 --- a/README.md +++ /dev/null @@ -1,84 +0,0 @@ -| Workflow | Badge | -| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| Automated tests | [](https://github.com/OpenEnergyPlatform/oemetadata/actions/workflows/metadata-test.yml) | -| PyPI Publish | [](https://pypi.org/project/oemetadata/) | -| Docs | [](https://openenergyplatform.github.io/oemetadata/) | - - -
-
-
-# Open Energy Family - Open Energy Metadata (OEMetadata)
-
-Open Energy Metadata (OEMetadata) is an energy metadata standard including a template, examples and a metadata schema.
-It is an extensive set of metadata based on the tabular data package specifications and the FAIR principles.
-The metadata contains multiple fields (keys) in a nested JSON structure.
-
-You can find the latest version right here:
-* [template.json](https://github.com/OpenEnergyPlatform/oemetadata/blob/develop/metadata/latest/template.json) contains an empty metadata string
-* [metadata_key_description.md](https://github.com/OpenEnergyPlatform/oemetadata/blob/develop/metadata/latest/metadata_key_description.md) contains a description of each metadata key
-* [example.json](https://github.com/OpenEnergyPlatform/oemetadata/blob/develop/metadata/latest/example.json) contains a basic metadata example
-
-
-## License / Copyright
-
-This repository is licensed under [MIT License (MIT)](https://spdx.org/licenses/MIT.html) -The oemetadata is licensed under [Creative Commons Zero v1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/)
-The oemetadata example and oemetadata template are licensed under [Creative Commons Zero v1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) - -## Installation - -`pip install oemetadata` - -## Usage Examples - -``` -from metadata.latest.example import OEMETADATA_LATEST_EXAMPLE - -print(OEMETADATA_LATEST_EXAMPLE) -``` - -``` -from metadata.latest.schema import OEMETADATA_LATEST_SCHEMA - -print(OEMETADATA_LATEST_SCHEMA) -``` - -``` -from metadata.latest.template import OEMETADATA_LATEST_TEMPLATE - -print(OEMETADATA_LATEST_TEMPLATE) -``` - -## Contributing - -For further contributing infos and conventions see: [CONTRIBUTING.md](https://github.com/OpenEnergyPlatform/oemetadata/blob/develop/CONTRIBUTING.md) - -## Release a new version -See the complete instructions in the [RELEASE_PROCEDURE](https://github.com/OpenEnergyPlatform/oemetadata/blob/develop/RELEASE_PROCEDURE.md). - -### Make PyPI release: - -1. Update the version in the setup.py file to reflect the new version number. -2. Follow these steps to utilize the release automation workflow: - -Testing Stage: - -- Create a new branch named "release/branch-name" to test your changes. -- Make sure all your changes are included in a single commit (until a more efficient workflow is determined). -- The release automation workflow is automatically executed, which will attempt to upload the package to the test.PyPI repository. -- If the upload is successful, the workflow will fail on subsequent attempts (as it should only be uploaded once successfully). - -Deployment Stage: - -- Merge the release branch into the "master" or "main" branch, depending on your repository's default branch. -- Publish a release on GitHub, documenting the changes made in this version. -- This action will trigger the automated workflow to release the new version to the official PyPI repository. - - -Manual steps are: - -``` -python3 setup.py sdist bdist_wheel -twine upload dist/* -``` diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..faa0d9ac --- /dev/null +++ b/README.rst @@ -0,0 +1,95 @@ + +.. figure:: https://user-images.githubusercontent.com/14353512/245271998-794e9d73-e728-4993-9ecf-4d0d08d96827.png + :align: left + :target: https://github.com/OpenEnergyPlatform/oemetadata + :alt: Repo logo + +================================= +Open Energy Metadata (OEMetadata) +================================= + +**An energy metadata standard including a metadata schema, templates, and examples.** + +.. list-table:: + :widths: auto + + * - License + - |badge_license| + * - Documentation + - |badge_documentation| + * - Publication + - + * - Development + - |badge_issue_open| |badge_issue_closes| |badge_pr_open| |badge_pr_closes| + * - Community + - |badge_contributing| |badge_contributors| |badge_repo_counts| + +.. contents:: + :depth: 2 + :local: + :backlinks: top + +Introduction +============ +| Open Energy Metadata (OEMetadata) is a metadata standard for the energy domain. +| It is an extensive set of metadata based on the tabular data package specifications and the FAIR principles. +| The metadata contains multiple fields (keys) in a nested JSON structure. + +You can find the latest version right here: + +- `template.json <./metadata/latest/template.json>`_ contains an empty metadata string +- `metadata_key_description.md <./metadata/latest/metadata_key_description.md>`_ contains a description of each metadata key +- `example.json <./metadata/latest/example.json>`_ contains a basic metadata example + +Documentation +============= +| The documentation is created with Markdown using `MkDocs
+See the [mkdocstrings documentation](https://mkdocstrings.github.io/). diff --git a/docs/code/install/index.md b/docs/code/install/index.md new file mode 100644 index 00000000..5706ee12 --- /dev/null +++ b/docs/code/install/index.md @@ -0,0 +1,7 @@ +# Install + +- requirements.txt +- requirements_dev.txt +- environment.yml +- setup.py +- pyproject.toml diff --git a/docs/code/style/index.md b/docs/code/style/index.md new file mode 100644 index 00000000..849c1eb4 --- /dev/null +++ b/docs/code/style/index.md @@ -0,0 +1,6 @@ +# Code Style +!!! note "Common python styles" + - Pep8 + - https://google.github.io/styleguide/pyguide.html + +TBD diff --git a/docs/css/extra.css b/docs/css/extra.css new file mode 100644 index 00000000..a9146c82 --- /dev/null +++ b/docs/css/extra.css @@ -0,0 +1,7 @@ +:root > * { + --md-primary-fg-color: #0f3b64; + --md-primary-fg-color--dark: #5d6cc0; + --md-typeset-a-color: #5ba6ec; + /* --md-text-font-color: #ffffff; */ + /* --md-primary-fg-color--light: #ECB7B7; */ + } \ No newline at end of file diff --git a/docs/development/collaboration/citation.md b/docs/development/collaboration/citation.md new file mode 100644 index 00000000..65828998 --- /dev/null +++ b/docs/development/collaboration/citation.md @@ -0,0 +1,3 @@ +# Citation + +See the *Cite this repository* function or [CITATION.cff](https://github.com/OpenEnergyPlatform/oemetadata/blob/develop/CITATION.cff) for citation of this repository. \ No newline at end of file diff --git a/docs/development/collaboration/code_of_conduct.md b/docs/development/collaboration/code_of_conduct.md new file mode 100644 index 00000000..90b9c77e --- /dev/null +++ b/docs/development/collaboration/code_of_conduct.md @@ -0,0 +1,4 @@ +# Code of Conduct + +This repository is following the [Contributor Covenant Code of Conduct](https://github.com/OpenEnergyPlatform/oemetadata/blob/production/CODE_OF_CONDUCT.md).
+Everyone is asked to be self-reflective and always maintain a good culture of discussion and active participation. diff --git a/docs/development/collaboration/contributing.md b/docs/development/collaboration/contributing.md new file mode 100644 index 00000000..7e10bff8 --- /dev/null +++ b/docs/development/collaboration/contributing.md @@ -0,0 +1,7 @@ +# Contributing + +This software is licensed under an open-source license and can be downloaded, +executed and modified.
+To contribute to the collaborative development follow the workflow described in +[CONTRIBUTING.md](https://github.com/OpenEnergyPlatform/oemetadata/blob/master/CONTRIBUTING.md). + \ No newline at end of file diff --git a/docs/development/collaboration/index.md b/docs/development/collaboration/index.md new file mode 100644 index 00000000..e67ec8ef --- /dev/null +++ b/docs/development/collaboration/index.md @@ -0,0 +1,4 @@ +# Collaboration + +This open-source software is a collaborative effort.
+The repository has several elements to provide necessary functions. diff --git a/docs/development/collaboration/license.md b/docs/development/collaboration/license.md new file mode 100644 index 00000000..8a901d01 --- /dev/null +++ b/docs/development/collaboration/license.md @@ -0,0 +1,4 @@ +# License + +This software is developed under an [open-source license](https://en.wikipedia.org/wiki/Open-source_license).
+The selected license can be read in the [LICENSE.txt](https://github.com/OpenEnergyPlatform/oemetadata/blob/production/LICENSE). diff --git a/docs/development/collaboration/users.md b/docs/development/collaboration/users.md new file mode 100644 index 00000000..d9639070 --- /dev/null +++ b/docs/development/collaboration/users.md @@ -0,0 +1,3 @@ +# Users + +Known user of this software can be added to [USERS.cff](https://github.com/OpenEnergyPlatform/oemetadata/blob/production/USERS.cff) for reference. diff --git a/docs/development/documentation/index.md b/docs/development/documentation/index.md new file mode 100644 index 00000000..128240b2 --- /dev/null +++ b/docs/development/documentation/index.md @@ -0,0 +1,36 @@ +# Documentation + +- README.rst +- CHANGELOG.md +- docs/ +- MkDocs +- mkdocstrings + + +## MkDocs +[MkDocs](https://www.mkdocs.org/) is a fast and simple static site generator that is used for documentation.
+The source files are written in Markdown, and configured with a single YAML configuration file `mkdocs.yml`.
+[Material theme](https://squidfunk.github.io/mkdocs-material/) enables +additional features and an elegant design. + +### Install +Install the required packages in a python environment.
+`pip install mkdocs` install MkDocs
+`pip install mkdocs-material` install the material theme + +### Build +Generate the documentation.
+`mkdocs serve` start the local live version of the documentation
+`mkdocs build` create a folder `site` with the documentation + +### Publish + +#### Manually +Publish documentation on **GitHub Pages**.
+`mkdocs gh-deploy` manually deploys the documentation files + +#### GitHub Action +Deploy the documentation with **GitHub Actions**.
+The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow.
+It is configured to be pushed to the branch `gh-page` and then deployed online.
+A commit on the `production` branch triggers the workflow. diff --git a/docs/development/git/gitignore.md b/docs/development/git/gitignore.md new file mode 100644 index 00000000..72e33f9e --- /dev/null +++ b/docs/development/git/gitignore.md @@ -0,0 +1,4 @@ +# Gitignore + +Copied from [A collection of useful .gitignore templates](https://github.com/github/gitignore).
+For more information about `.gitignore` files, see the [Ignoring Files chapter](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) of the Pro Git book. diff --git a/docs/development/git/index.md b/docs/development/git/index.md new file mode 100644 index 00000000..f831d600 --- /dev/null +++ b/docs/development/git/index.md @@ -0,0 +1,10 @@ +# Git + +- .gitignore + +Copied from (A collection of useful .gitignore templates)[https://github.com/github/gitignore].
+For more information about how `.gitignore` files work, and how to use them, see (Ignoring Files chapter)[https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring] of the Pro Git book. + +- issue_template +- pull_request_template +- workflows (testing) diff --git a/docs/development/git/test-driven-developement-workflow.md b/docs/development/git/test-driven-developement-workflow.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/development/release/index.md b/docs/development/release/index.md new file mode 100644 index 00000000..2a4cc1a8 --- /dev/null +++ b/docs/development/release/index.md @@ -0,0 +1,6 @@ +# Release + +- RELEASE_PROCEDURE.md +- VERSION +- MANIFEST.in +- .bumpversion.cfg diff --git a/docs/img/OpenEnergyFamily_Logo_OEMetadata_white.png b/docs/img/OpenEnergyFamily_Logo_OEMetadata_white.png new file mode 100644 index 00000000..9f555143 Binary files /dev/null and b/docs/img/OpenEnergyFamily_Logo_OEMetadata_white.png differ diff --git a/docs/img/logo_oefamily_small.png b/docs/img/logo_oefamily_small.png new file mode 100644 index 00000000..49e4bd08 Binary files /dev/null and b/docs/img/logo_oefamily_small.png differ diff --git a/docs/img/logo_rli_small.png b/docs/img/logo_rli_small.png new file mode 100644 index 00000000..06a2f6c8 Binary files /dev/null and b/docs/img/logo_rli_small.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..a02360a0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,18 @@ +--- +hide: + - footer + - toc +--- + +# Welcome to the Documentation of the Open Energy Metadata + +## Open Energy Metadata + +Open Energy Metadata (OEMetadata) is an energy metadata standard including a template, examples and a metadata schema.
+It is an extensive set of metadata based on the tabular data package specifications and the FAIR principles.
+The metadata contains multiple fields (keys) in a nested JSON structure. + +## Documentation Structure + +The documentation is separated into two main sections: +`Development` and `Metadata Documentation`.
diff --git a/docs/metadata/index.md b/docs/metadata/index.md new file mode 100644 index 00000000..e07b05ac --- /dev/null +++ b/docs/metadata/index.md @@ -0,0 +1,7 @@ +# Metadata Documentation + +The OEMetadata contains the following files: + +- `metadata_key_description.md` contains a full description of each metadata key. +- `template.json` contains an empty metadata string with all fields. +- `example.json` contains a basic metadata example. diff --git a/docs/metadata/metadata_key_description.md b/docs/metadata/metadata_key_description.md new file mode 100644 index 00000000..2c26b4ad --- /dev/null +++ b/docs/metadata/metadata_key_description.md @@ -0,0 +1,203 @@ +# OEMetadata - Key Description + +This pages describes the key of **OEMetadata version 2.0 .**
+You can have a look at an empty [template](https://github.com/OpenEnergyPlatform/oemetadata/blob/master/metadata/latest/template.json) and a filled out [example](https://github.com/OpenEnergyPlatform/oemetadata/blob/master/metadata/latest/example.json) of the metadata string. + + +## JSON Format +The JSON format offers different formats: +* key-value pair: + ```JSON + {"key":"value"} + ``` +* array: + ```JSON + {"key": + ["value","value"]} + ``` +* object {nested key}: + ```JSON + {"key": { + "key_a":"value", + "key_b":"value"}} + ``` +* array of objects {nested array}: + ```JSON + {"key": [ + {"key_a":"value"}, + {"key_a":"value"}]} + ``` + + +## Metadata keys with a description and example + +If a field is not applicable use: 'null'. +If a value is not yet available, use: 'ToDo'. + +### Collection Keys +| # | Key | Description | Example | Badge | +|---|-----------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------|--------| +| 1 | name | A filename or database conform collection name. | oep_oemetadata | Iron | +| 2 | title | A human readable collection name. | OEP OEMetadata | Silver | +| 3 | id | A unique identifier (UUID/DOI) for the collection. | https://databus.openenergyplatform.org/oeplatform/reference | Silver | +| 4 | resources | An array of objects of the resources. The collection can contain several (database) tables. | | | + +### Resource - Linked Data Keys +| # | Key | Description | Example | Badge | +|---|----------|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------| +| 1 | @id | A Uniform Resource Identifier (URI) that links the resource via the OpenEnergyDatabus (DBpedia Databus). | https://databus.openenergyplatform.org/oeplatform/supply/wri_global_power_plant_database/2022-11-07 | Platinum | +| 2 | @context | Explanation of metadata keys in ontology terms. | https://raw.githubusercontent.com/OpenEnergyPlatform/oemetadata/master/metadata/latest/context.json | Platinum | + +### Resource - General Keys +| # | Key | Description | Example | Badge | +|------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|----------| +| 1 | name | A filename or database conform table name. | oep_oemetadata_table_example | Iron | +| 2 | topics | An array of predefined topics that correspond to the database schemas of the OEP. | model_draft, reference | Bronze | +| 3 | title | A human readable table name. | OEP OEMetadata Example Table | Silver | +| 4 | path | A unique identifier (URI/UUID/DOI) for the table or file. | http://openenergyplatform.org/dataedit/view/model_draft/oep_oemetadata_table_example | Bronze | +| 5 | description | A description of the table. It should be usable as summary information for the table that is described by the metadata. | Example table used to illustrate the OEMetadata structure and meaning. | Silver | +| 6 | languages | An array of languages used within the described data structures (e.g. titles, descriptions). The language key can be repeated if more languages are used. Standard: IETF (BCP47) | en-GB, de-DE, fr-FR | Gold | +| 7 | **subject** | An array of objects that references to the subjects of the resource in ontology terms. | | +| 7.1 | name | A class label of the ontology term. | energy | Platinum | +| 7.2 | path | A unique identifier (URI/IRI) of the ontology class. | https://openenergy-platform.org/ontology/oeo/OEO_00000150 | Platinum | +| 8 | keywords | An array of freely selectable keywords that help with searching and structuring. The keyword are used and managed in the OEP as table tags. | example, ODbL-1.0, NFDI4Energy | Silver | +| 9 | publicationDate | A date of publication of the data or metadata. The date format is ISO 8601 (YYYY-MM-DD). | 2024-10-15 | Bronze | +| 10 | **embargoPeriod** | An object that describes the embargo period during which public access to the data is not allowed. | +| 10.1 | start | The start date of the embargo period. The date of the data (metadata) upload. | 2024-10-11 | Bronze | +| 10.2 | end | The end date of the embargo period. This is the envisioned publication date. | 2025-01-01 | Bronze | +| 10.3 | isActive | A boolean key that indicates if the embargo period is currently active. Must be changed to False on the embargo period end date. | True | Bronze | + +### Resource - Context Keys +| # | Key | Description | Example | Badge | +|-----|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|-------| +| 1 | **context** | An object that describes the general setting, environment, or project leading to the creation or maintenance of this dataset. In science this is can be the research project. | | | +| 1.1 | title | A title of the associated project. | NFDI4Energy | Gold | +| 1.2 | homepage | A URL of the project. | https://nfdi4energy.uol.de/ | Gold | +| 1.3 | documentation | A URL of the project documentation. | https://nfdi4energy.uol.de/sites/about_us/ | Gold | +| 1.4 | sourceCode | A URL of the source code of the project. | https://github.com/NFDI4Energy | Gold | +| 1.5 | contact | A reference to the creator or maintainer of the data set. It can be an email address or a GitHub handle. | info@nfdi4energy.org | Gold | +| 1.6 | grantNo | An identifying grant number. In case of a publicly funded project, this number is assigned by the funding agency. | 501865131 | Gold | +| 1.7 | fundingAgency | A name of the entity providing the funding. This can be a government agency or a company. | Deutsche Forschungsgemeinschaft (DFG) | Gold | +| 1.8 | fundingAgencyLogo | A URL to the logo or image of the funding agency. | https://upload.wikimedia.org/wikipedia/commons/8/86/DFG-logo-blau.svg | Gold | +| 1.9 | publisherLogo | A URL to the logo of the publishing agency of data. | https://reiner-lemoine-institut.de//wp-content/uploads/2015/09/rlilogo.png | Gold | + +### Resource - Spatial Keys +| # | Key | Description | Example | Badge | +|-------|-----------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|----------| +| 1 | **spatial** | An object that describes the spatial context of the data. | | | +| 1.1 | **location** | An object that describes a covered area or region. | | | +| 1.1.1 | address | An address of the location of the data. May be specified with street name, house number, zip code, and city name. | Rudower Chaussee 12, 12489 Berlin | Silver | +| 1.1.2 | @id | A path or URI to a specific location. It can use Wikidata or OpenStreetMap. | https://www.wikidata.org/wiki/Q77077223 | Platinum | +| 1.1.3 | longitude | The latitude (lat) information of the location. | 52.432822 | Gold | +| 1.1.4 | longitude | The longitude (lon) information of the location. | 13.5351004 | Gold | +| 1.2 | **extent** | An object that describes a covered area or region. | | | +| 1.2.1 | name | The name of the region. | Berlin | Silver | +| 1.2.2 | @id | A URI reference for the region. | https://www.wikidata.org/wiki/Q64 | Platinum | +| 1.2.3 | resolutionValue | The value of the resolution. | 100 | Silver | +| 1.2.4 | resolutionUnit | The unit of the resolution. | m | Silver | +| 1.2.5 | boundingBox | The covered area specified by the coordinates of a bounding box. The format is [minLon, minLat, maxLon, maxLat] or [W,S,E,N]. | [13.08825, 52.33859, 13.76104, 52.6754] | Gold | +| 1.2.6 | crs | The Coordinate Reference System, specified as an EPSG code. | EPSG:4326 | Gold | + +### Resource - Temporal Keys +| # | Key | Description | Example | Badge | +|-------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|--------| +| 1 | **temporal** | An object with the time period covered in the data. Temporal information should contain either a "referenceDate" or the keys that describe a time series, in rare cases both. | | | +| 1.1 | referenceDate | A base year, month or day. The time for which the data is should be accurate. Date Format is ISO 8601. | 2020-01-01 | Silver | +| 1.2 | **timeseries** | An array that describes the timeseries. | | | +| 1.2.1 | start | The start time of a time series. | 2020-01-01T00:00:00+00:00 | Silver | +| 1.2.2 | end | The temporal end point of a time series. | 2020-01-01T23:59:30+00:00 | Silver | +| 1.2.3 | resolution | The time span between individual information points in a time series. | 30 s | Silver | +| 1.2.4 | alignment | An indicator of whether timestamps in a time series are to the left, right or in the centre. | left | Silver | +| 1.2.5 | aggregationType | An indicator of whether the values are a sum, an average or a current value. | current | Silver | + +### Resource - Sources Keys +| # | Key | Description | Example | Badge | +|-------|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------| +| 1 | **sources** | An array of objects with the used and underlying sources of the data and metadata. | | | +| 1.1 | title | A human readable title of the source, a document title or organisation name. | IPCC Sixth Assessment Report (AR6) - Climate Change 2023 - Synthesis Report | Bronze | +| 1.2 | description | A free text description of the source. | A Report of the Intergovernmental Panel on Climate Change | Bronze | +| 1.3 | path | A URL to the original source. | https://www.ipcc.ch/report/ar6/syr/downloads/report/IPCC_AR6_SYR_FullVolume.pdf | Bronze | +| 1.4 | **licenses** | An array of objects of licenses under which the described source is provided. See https://openenergyplatform.github.io/academy/courses/08_licensing/ for further information. | | | +| 1.4.1 | name | The [SPDX](https://spdx.org/licenses/) identifier. | ODbL-1.0 | Bronze | +| 1.4.2 | title | The official (human-readable) title of the license. | Open Data Commons Open Database License 1.0 | Bronze | +| 1.4.3 | path | A link or path to the license text. | https://opendatacommons.org/licenses/odbl/1-0/index.html | Bronze | +| 1.4.4 | instruction | A short description of rights and obligations. The use of [tl;drLegal](https://tldrlegal.com/) is recommended. | You are free to share and change, but you must attribute, and share derivations under the same license. See https://tldrlegal.com/license/odc-open-database-license-odbl for further information. | Bronze | +| 1.4.5 | attribution | A copyright owner of the **source**. Must be provided if attribution licenses are used. | © Intergovernmental Panel on Climate Change 2023 | Bronze | +| 1.4.6 | copyrightStatement | A link or path that proves that the source or data has the appropriate license. This can be a page number or website imprint. | https://www.ipcc.ch/copyright/ | Bronze | + +### Resource - Licenses Keys +| # | Key | Description | Example | Badge | +|-----|--------------|----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------| +| 1 | **licenses** | An array of objects of licenses under which the described data is provided. | | | +| 1.1 | name | The [SPDX](https://spdx.org/licenses/) identifier. | ODbL-1.0 | Bronze | +| 1.2 | title | The official (human-readable) title of the license. | Open Data Commons Open Database License 1.0 | Bronze | +| 1.3 | path | A link or path to the license text. | https://opendatacommons.org/licenses/odbl/1-0/index.html | Bronze | +| 1.4 | instruction | A short description of rights and obligations. The use of [tl;drLegal](https://tldrlegal.com/) is recommended. | You are free to share and change, but you must attribute, and share derivations under the same license. See https://tldrlegal.com/license/odc-open-database-license-odbl for further information. | Bronze | +| 1.5 | attribution | A copyright owner of the **data**. Must be provided if attribution licenses are used. | © Reiner Lemoine Institut | Bronze | + +### Resource - Provenance Keys +| # | Key | Description | Example | Badge | +|-----|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|--------| +| 1 | **contributors** | An array of objects of the people or organizations who contributed to the data or metadata. | | | +| 1.1 | title | A full name of the contributor. | Ludwig Hülk | Bronze | +| 1.2 | path | A qualified link or path pointing to a relevant location online for the contributor. This can be the GitHub page or ORCID. | https://github.com/Ludee | Bronze | +| 1.3 | organization | A string describing the organization this contributor is affiliated to. This can be relevant for the copyright. | Reiner Lemoine Institut | Bronze | +| 1.4 | roles | An array describing the roles of the contributor. A role is recommended to follow an established vocabulary, such as DataCite Metadata Schema’s contributorRole or CreDIT. Useful roles to indicate are: creator, contact, and dataCurator. | creator, dataCurator | Bronze | +| 1.5 | date | The date of the final contribution. Date Format is ISO 8601. | 2024-10-21 | Bronze | +| 1.6 | object | The target of the contribution. This can be the data, the metadata or both (data and metadata). | data and metadata | Bronze | +| 1.7 | comment | A free-text commentary on what has been done. | Add general context. | Bronze | + +### Resource - Type Keys +| # | Key | Description | Example | Badge | +|---|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|------------|-------| +| 1 | type | The 'table' type indicates that the resource is tabular as per 'Frictionless Tabular Data' definition. | table | Gold | +| 2 | format | A file extension format. Possible options are 'csv', 'xlsx', 'json', 'PostgreSQL', 'SQLite' and other standard file extensions. | PostgreSQL | Gold | +| 3 | encoding | Specifies the character encoding of the resource's data file. The default is 'UTF-8'. The values should be one of the 'Preferred MIME Names'. | UTF-8 | Gold | + +#### Resource - Fields Keys +| # | Key | Description | Example | Badge | +|---------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|----------| +| 1 | **schema** | An object that describes the structure of a table. It contains all fields (columns of the table), the primary key and optional foreign keys. | | | +| 1.1 | **fields** | An array of objects that describes a field (column) and its detailed information. | | | +| 1.1.1 | name | The name of the field. The name may only consist of lowercase alphanumeric characters or underscores. It must not begin with a number or an underscore. | year | Iron | +| 1.1.2 | description | A text describing the field. | Reference year for which the data were collected. | Silver | +| 1.1.3 | type | The data type of the field. In case of a geom column in a database, also indicate the shape and CRS. | geometry(Point, 4326) | Iron | +| 1.1.4 | nullable | A boolean key to specify that a column can be nullable. True is the default value. | True | Iron | +| 1.1.5 | unit | The unit of a field. If it does not apply, use 'null'. If the unit is given in a separate field, reference this field (e.g. 'unit'). Use a space between numbers and units (100 m). | MW | Silver | +| 1.1.6 | **isAbout** | An array of objects that describes the field in ontology terms. | +| 1.1.6.1 | name | The class label of the ontology term. | wind energy converting unit | Platinum | +| 1.1.6.2 | path | The path of the ontology term (IRI). | https://openenergy-platform.org/ontology/oeo/OEO_00000044 | Platinum | +| 1.1.7 | **valueReference** | An array of objects for an extended description of the values in the column in ontology terms. | | | +| 1.1.7.1 | value | The name of the value in the column. | onshore | Platinum | +| 1.1.7.2 | name | The class label of the ontology term in the column. | onshore wind farm | Platinum | +| 1.1.7.3 | path | The path of the ontology term (IRI) in the column. | https://openenergy-platform.org/ontology/oeo/OEO_00000311 | Platinum | + +#### Resource - Properties Keys +| # | Key | Description | Example | Badge | +|---------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|-------| +| 1.2 | primaryKey | An array of fields that uniquely identifies each row in the table. The default value is the “id” column. | id | Iron | +| 1.3 | **foreignKeys** | An array of objects with foreign keys that describe a field that relates to a field in another table. | | | +| 1.3.1 | fields | An array of fields in the table that is constrained by the foreign key. | id, version | Iron | +| 1.3.2 | **reference** | The reference to the foreign table. | | | +| 1.3.2.1 | resource | The referenced foreign table. | model_draft.oep_oemetadata_table_example_version | Iron | +| 1.3.2.2 | fields | The foreign resource column. | id, version | Iron | +| 1.4 | **dialect** | The Dialect defines a simple format for describing the various dialects of CSV files in a language-independent manner. In a database, the values in the fields are 'null'. | | | +| 1.4.1 | delimiter | The delimiter specifies the character sequence which should separate fields (columns). Common characters are ',' (comma), ';' (semicolon), '.' (point) and '\t' (tab). | , | Iron | +| 1.4.2 | decimalSeparator | The symbol used to separate the integer part from the fractional part of a number written in decimal form. Depending on language and region this symbol can be '.' or ','. | . | Iron | + +### Resource - Review Keys +| # | Key | Description | Example | +|-----|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| 1. | **review** | The metadata on the OEP can go through an open peer review process. See the Academy course [Open Peer Review](https://openenergyplatform.github.io/academy/courses/09_peer_review/) for further information. | | +| 1.1 | path | A link or path to the documented open peer review. | https://www.example.com | +| 1.2 | badge | A badge of either Iron, Bronze, Silver, Gold or Platinum is used to label the quality of the metadata. | Platinum | + +### MetaMetadata Keys +| # | Key | Description | Example | +|-------|---------------------|--------------------------------------------------------------------------------------|----------------------------------------------------| +| 1 | **metaMetadata** | An object that describes the metadata themselves, their format, version and license. | | +| 1.1 | metadataVersion | Type and version number of the metadata. | OEMetadata-2.0 | +| 1.2 | **metadataLicense** | The license of the provided metadata. | | +| 1.2.1 | name | The [SPDX](https://spdx.org/licenses/) identifier. | CC0-1.0 | +| 1.2.2 | title | The official (human-readable) title of the license. | Creative Commons Zero v1.0 Universal | +| 1.2.3 | path | A link or path to the license text. | https://creativecommons.org/publicdomain/zero/1.0/ | diff --git a/metadata/v20/build_source/README.md b/metadata/v20/build_source/README.md index 198d6cac..1c8b89dc 100644 --- a/metadata/v20/build_source/README.md +++ b/metadata/v20/build_source/README.md @@ -4,9 +4,9 @@ The OEMetaData uses the json schema specification to define the structure of the Over the years it also became an constant issue to keep all parts of the release consistent with all changes made to the schema.json. The tooling enables developers to only edit the schema.json and then generate the relevant example and template JSON files based on the OEMetaData specification and the example values available as part of the schema.json. -## Content +## Structure -The structure of the OEMetaData release contents changed a bit. While the known schema, example and template json and python files are still available the new directory 'build_source' is now also part of each release. It contains two sub directories: `build_source/schemas/` includes the schema parts, if you want to extend the OEMetaData specification this is the directory you should maintain. The `build_source/scripts/` implements the tooling. There are 3 scripts for schema ref resolve and schema, example and template JSON file generation. The settings script is used to share common information across python modules, in this case it includes mainly the path´s. +The structure of the OEMetaData release contents changed a bit. While the known schema, example and template json and python files are still available the new directory 'build_source' is now also part of each release. It contains two sub directories: `build_source/schemas/` includes the schema parts, if you want to extend the OEMetaData specification this is the directory you should maintain. The `build_source/scripts/` implements the tooling. There are 3 scripts for schema ref resolve and schema, example and template JSON file generation. The settings script is used to share common information across python modules, in this case it includes mainly the path´s. ## Usage @@ -14,6 +14,7 @@ Using bash terminal on wsl ubuntu distribution with Python >3.8 installed Create a python3 environment. + #assuming you are currently in the oemetadata base directory. python3 -m venv env Install the requirements. @@ -26,13 +27,13 @@ Navigate to the tooling directory to ease usage and run the tooling as python sc #assuming you are currently in the oemetadata base directory. cd metadata/v20/build_source/scripts/ # generate the oemetadata json schema based on json schemas in the schemas directory - python resolve_schema_refs.py + python metadata/v20/build_source/scripts/resolve_schema_refs.py # use option --debug to show additional logging information - python resolve_schema_refs.py --debug + python metadata/v20/build_source/scripts/resolve_schema_refs.py --debug Generate the example and template - python generate_example_from_schema.py - python generate_template_from_schema.py + python metadata/v20/build_source/scripts/generate_example_from_schema.py + python metadata/v20/build_source/scripts/generate_template_from_schema.py diff --git a/metadata/v20/build_source/schemas/collection.json b/metadata/v20/build_source/schemas/collection.json index 72f9cf81..a26edcc3 100644 --- a/metadata/v20/build_source/schemas/collection.json +++ b/metadata/v20/build_source/schemas/collection.json @@ -20,9 +20,19 @@ "string", "null" ], - "badge": "Silver", + "badge": "Bronze", "title": "Collection Title" }, + "description": { + "description": "A free text description of the collection.", + "example": "A collection of tables for the OEMetadata examples.", + "type": [ + "string", + "null" + ], + "badge": "Bronze", + "title": "Collection Description" + }, "id": { "description": "A unique identifier (UUID/DOI) for the collection.", "example": "https://databus.openenergyplatform.org/oeplatform/reference", diff --git a/metadata/v20/build_source/schemas/context.json b/metadata/v20/build_source/schemas/context.json index 475c3d71..7b16c300 100644 --- a/metadata/v20/build_source/schemas/context.json +++ b/metadata/v20/build_source/schemas/context.json @@ -47,26 +47,36 @@ "badge": "Gold", "title": "Source Code" }, - "contact": { - "description": "A reference to the creator or maintainer of the data set. This can be an email address or a GitHub handle.", - "example": "contact@example.com", + "publisher": { + "description": "The publishing agency of the data. This can be the OEP.", + "example": "Open Energy Platform (OEP)", "type": [ "string", "null" ], "badge": "Gold", - "title": "E-Mail Contact", - "format": "email" + "title": "Publisher" + },"publisherLogo": { + "description": "A URL to the logo of the publishing agency of data.", + "example": "https://github.com/OpenEnergyPlatform/organisation/blob/production/logo/OpenEnergyFamily_Logo_OpenEnergyPlatform.svg", + "type": [ + "string", + "null" + ], + "badge": "Gold", + "title": "Publisher Logo", + "format": "uri" }, - "grantNo": { - "description": "An identifying grant number. In case of a publicly funded project, this number is assigned by the funding agency.", - "example": "501865131", + "contact": { + "description": "A reference to the creator or maintainer of the data set. This can be an email address or a GitHub handle.", + "example": "contact@example.com", "type": [ "string", "null" ], "badge": "Gold", - "title": "Grant Number" + "title": "E-Mail Contact", + "format": "email" }, "fundingAgency": { "description": "A name of the entity providing the funding. This can be a government agency or a company.", @@ -89,16 +99,15 @@ "title": "Funding Agency Logo", "format": "uri" }, - "publisherLogo": { - "description": "A URL to the logo of the publishing agency of data.", - "example": "https://reiner-lemoine-institut.de//wp-content/uploads/2015/09/rlilogo.png", + "grantNo": { + "description": "An identifying grant number. In case of a publicly funded project, this number is assigned by the funding agency.", + "example": "501865131", "type": [ "string", "null" ], "badge": "Gold", - "title": "Publisher Logo", - "format": "uri" + "title": "Grant Number" } }, "badge": "Gold", diff --git a/metadata/v20/metadata_key_description.md b/metadata/v20/metadata_key_description.md index 6af66b88..5551a4c1 100644 --- a/metadata/v20/metadata_key_description.md +++ b/metadata/v20/metadata_key_description.md @@ -35,12 +35,13 @@ If a field is not applicable use: 'null'. If a value is not yet available, use: 'ToDo'. ### Collection Keys -| # | Key | Description | Example | Badge | -|---|-----------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------|--------| -| 1 | name | A filename or database conform collection name. | oep_oemetadata | Iron | -| 2 | title | A human readable collection name. | OEP OEMetadata | Silver | -| 3 | id | A unique identifier (UUID/DOI) for the collection. | https://databus.openenergyplatform.org/oeplatform/reference | Silver | -| 4 | resources | An array of objects of the resources. The collection can contain several (database) tables. | | | +| # | Key | Description | Example | Badge | +|---|-------------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------|--------| +| 1 | name | A filename or database conform collection name. | oep_oemetadata | Iron | +| 2 | title | A human readable collection name. | OEP OEMetadata | Bronze | +| 3 | description | A free text description of the collection. | A collection of tables for the OEMetadata examples. | Bronze | +| 4 | id | A unique identifier (UUID/DOI) for the collection. | https://databus.openenergyplatform.org/oeplatform/reference | Silver | +| 5 | resources | An array of objects of the resources. The collection can contain several (database) tables. | | | ### Resource - Linked Data Keys | # | Key | Description | Example | Badge | @@ -68,18 +69,19 @@ If a value is not yet available, use: 'ToDo'. | 10.3 | isActive | A boolean key that indicates if the embargo period is currently active. Must be changed to False on the embargo period end date. | True | Bronze | ### Resource - Context Keys -| # | Key | Description | Example | Badge | -|-----|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|-------| -| 1 | **context** | An object that describes the general setting, environment, or project leading to the creation or maintenance of this dataset. In science this is can be the research project. | | | -| 1.1 | title | A title of the associated project. | NFDI4Energy | Gold | -| 1.2 | homepage | A URL of the project. | https://nfdi4energy.uol.de/ | Gold | -| 1.3 | documentation | A URL of the project documentation. | https://nfdi4energy.uol.de/sites/about_us/ | Gold | -| 1.4 | sourceCode | A URL of the source code of the project. | https://github.com/NFDI4Energy | Gold | -| 1.5 | contact | A reference to the creator or maintainer of the data set. It can be an email address or a GitHub handle. | info@nfdi4energy.org | Gold | -| 1.6 | grantNo | An identifying grant number. In case of a publicly funded project, this number is assigned by the funding agency. | 501865131 | Gold | -| 1.7 | fundingAgency | A name of the entity providing the funding. This can be a government agency or a company. | Deutsche Forschungsgemeinschaft (DFG) | Gold | -| 1.8 | fundingAgencyLogo | A URL to the logo or image of the funding agency. | https://upload.wikimedia.org/wikipedia/commons/8/86/DFG-logo-blau.svg | Gold | -| 1.9 | publisherLogo | A URL to the logo of the publishing agency of data. | https://reiner-lemoine-institut.de//wp-content/uploads/2015/09/rlilogo.png | Gold | +| # | Key | Description | Example | Badge | +|------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|-------| +| 1 | **context** | An object that describes the general setting, environment, or project leading to the creation or maintenance of this dataset. In science this is can be the research project. | | | +| 1.1 | title | A title of the associated project. | NFDI4Energy | Gold | +| 1.2 | homepage | A URL of the project. | https://nfdi4energy.uol.de/ | Gold | +| 1.3 | documentation | A URL of the project documentation. | https://nfdi4energy.uol.de/sites/about_us/ | Gold | +| 1.4 | sourceCode | A URL of the source code of the project. | https://github.com/NFDI4Energy | Gold | +| 1.5 | publisher | The publishing agency of the data. This can be the OEP. | Open Energy Platform (OEP) | Gold | +| 1.6 | publisherLogo | A URL to the logo of the publishing agency of data. | https://github.com/OpenEnergyPlatform/organisation/blob/production/logo/OpenEnergyFamily_Logo_OpenEnergyPlatform.svg | Gold | +| 1.7 | contact | A reference to the creator or maintainer of the data set. It can be an email address or a GitHub handle. | info@nfdi4energy.org | Gold | +| 1.8 | fundingAgency | A name of the entity providing the funding. This can be a government agency or a company. | Deutsche Forschungsgemeinschaft (DFG) | Gold | +| 1.9 | fundingAgencyLogo | A URL to the logo or image of the funding agency. | https://upload.wikimedia.org/wikipedia/commons/8/86/DFG-logo-blau.svg | Gold | +| 1.10 | grantNo | An identifying grant number. In case of a publicly funded project, this number is assigned by the funding agency. | 501865131 | Gold | ### Resource - Spatial Keys | # | Key | Description | Example | Badge | diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..86ef922e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,83 @@ +# Project +site_name: Open Energy Metadata +site_url: +site_description: Open Energy Metadata (OEMetadata) is an energy metadata standard including a template, examples and a metadata schema. + +# Repository +repo_name: OpenEnergyPlatform/oemetadata +repo_url: https://github.com/OpenEnergyPlatform/oemetadata +docs_dir: docs + +# Configuration +theme: + name: material + logo: img/OpenEnergyFamily_Logo_OEMetadata_white.png + palette: + # Palette toggle for light mode + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + icon: + repo: fontawesome/brands/github + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.indexes + - navigation.path + - navigation.tracking + - navigation.top + - toc.follow + +# extensions +markdown_extensions: + - admonition + - toc: + permalink: 💙 + +plugins: +- mkdocstrings: + +# Customization +extra: + generator: false + homepage: https://openenergy-platform.org/ + +extra_css: + - css/extra.css + +# Navigation +nav: + - Home: index.md + - Development: + - Collaboration: + - development/collaboration/index.md + - License: development/collaboration/license.md + - Citation: development/collaboration/citation.md + - Contributing: development/collaboration/contributing.md + - Users: development/collaboration/users.md + - Code of Conduct: development/collaboration/code_of_conduct.md + - Git: + - development/git/index.md + - Gitignore: development/git/gitignore.md + - Documentation: + - development/documentation/index.md + - Release: + - development/release/index.md + - Metadata Documentation: + - metadata/index.md + - Key Description: metadata/metadata_key_description.md +# - Code Documentation: +# - Install: +# - code/install/index.md +# - Code Style: +# - code/style/index.md +# - Functions: +# - code/index.md +# - code/code_example.md diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 00000000..958268d3 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,3 @@ +mkdocs +mkdocs-material +mkdocstrings \ No newline at end of file