Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise the documentation to CodeMeta v3 #51

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Revise the documentation to CodeMeta v3 #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d87241c
Update examples to CodeMeta v3
Mar 31, 2025
61f9383
Update supported CodeMeta versions
Mar 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 9 additions & 12 deletions content/jsonld.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,18 @@
title: "The Codemeta JSON-LD Representation"
---


CodeMeta uses JSON-LD to represent and translate between software metadata formats. JSON-LD lead developer Manu Sporny explains how JSON-LD works in this short clip:

CodeMeta uses JSON-LD to represent and translate between software metadata formats.
JSON-LD lead developer Manu Sporny explains how JSON-LD works in this short clip:

{{< youtube Tm3fD89dqRE >}}



## The JSON-LD Context File

The current codemeta context file can be found at [![DOI](https://img.shields.io/badge/doi%3A-10.5063%2FSCHEMA%2FCODEMETA--2.0-blue.svg)](https://doi.org/10.5063/schema/codemeta-2.0)



CodeMeta properties are built on and extend software properties from <https://schema.org>. A list of all properties provided by the current CodeMeta `context` file can be found on the [terms](/terms) page. Here's an example [codemeta.json file](https://github.com/codemeta/codemetar/blob/master/codemeta.json) for the `codemetar` R package.

## Compaction & expansion examples:
The current codemeta context file can be found at
[![W3ID CodeMeta v3](https://img.shields.io/badge/W3ID-CodeMeta_v3-blue)](https://w3id.org/codemeta/3.0)

CodeMeta properties are built on and extend software properties from
<https://schema.org>. A list of all properties provided by the current CodeMeta
`context` file can be found on the [terms](/terms) page. Here's an example
[codemeta.json file](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)
for the `gem-pasteur/macsyfinder` project.
23 changes: 9 additions & 14 deletions content/tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,44 +8,39 @@ This page lists some existing tools to help with CodeMeta files

#### File Generation

Some of the early tools still need a little updating to use the latest version of the codemeta context.
Some of the early tools still need a little updating to use the latest version of the codemeta context.

{.table .table-striped}

tool | language | codemeta version | maintainer | notes
tool | language | codemeta versions | maintainer | notes
-----|----------|------------------|------------|--------------
[CodeMeta file generator](https://gist.github.com/arfon/478b2ed49e11f984d6fb) | Ruby | 0.1.0 | [arfon](http://github.com/arfon) | (no support for current schema)
[Bolognese](https://github.com/datacite/bolognese) | Ruby | 1.0.0 | [mfenner](https://github.com/mfenner) | primarily a tool for conversion between formats provided by DataCite, including codemeta and schema.org
[codemetar](https://ropensci.github.io/codemetar) | R | 2.0.0 | [cboettig](https://github.com/cboettig) | Generate codemeta for R packages; + generic codemeta manipulation
[codemetapy](https://github.com/proycon/codemetapy) | Python | 2.0.0 | [proycon](https://github.com/proycon) | Generate codemeta for Python, NodeJS, Java packages and others; + generic codemeta manipulation
[codemetapy](https://github.com/proycon/codemetapy) | Python | 2.0.0, 3.0.0 | [proycon](https://github.com/proycon) | Generate codemeta for Python, NodeJS, Java packages and others; + generic codemeta manipulation
[tributors](https://con.github.io/tributors/) | Python | 2.0.0 | [vsoch](https://github.com/vsoch) | Generate codemeta contributors section from GitHub API and Orcid API
[cff-converter](https://github.com/citation-file-format/cff-converter-python) | Python | 2.0.0 | [jspaaks](https://github.com/jspaaksh) | Convert `CITATION.cff` files to codemeta
[CodeMeta generator](https://codemeta.github.io/codemeta-generator/) | Javascript | 2.0.0 | [ProgVal](https://github.com/ProgVal) | Online form to create or complete a codemeta file
[codemeta-harvester](https://github.com/proycon/codemeta-harvester) | POSIX Shell | 2.0.0 | [proycon](https://github.com/proycon) | Automatic software metadata conversion pipeline that uses codemetapy and other tools
[codemeta-server](https://github.com/proycon/codemeta-server) | Python | 2.0.0 | [proycon](https://github.com/proycon) | Webservice offering an API (including SPARQL) and simple human web-interface so search and browse software metadata
[openCARP-CI](https://opencarp.org/CI) | Python | openCARP developers | GitLab CI pipelines including the conversion from CodeMeta to other formats (Citation File Format (CFF), DataCite, BagIt and BagPack)

[CodeMeta generator](https://codemeta.github.io/codemeta-generator/) | Javascript | 2.0.0, 3.0.0 | [ProgVal](https://github.com/ProgVal) | Online form to create or complete a codemeta file
[codemeta-harvester](https://github.com/proycon/codemeta-harvester) | POSIX Shell | 2.0.0, 3.0.0 | [proycon](https://github.com/proycon) | Automatic software metadata conversion pipeline that uses codemetapy and other tools
[codemeta-server](https://github.com/proycon/codemeta-server) | Python | 2.0.0, 3.0.0 | [proycon](https://github.com/proycon) | Webservice offering an API (including SPARQL) and simple human web-interface so search and browse software metadata
[openCARP-CI](https://git.opencarp.org/openCARP/openCARP-CI) | Python | 2.0.0 | [openCARP developers](https://opencarp.org/) | GitLab CI pipelines including the conversion from CodeMeta to other formats (Citation File Format (CFF), DataCite, BagIt and BagPack)

#### Integrations


Integrations indicate existing platforms & services which understand CodeMeta descriptions. These do not provide a user-facing software tool for generating codemeta.json, but can ingest
existing codemeta.json files automatically.

{.table .table-striped}

Name | Description | Authors | Language | Codemeta Version
Name | Description | Authors | Language | Codemeta Versions
-----|-------------|----------|----------|--------------------
[Fidgit](https://github.com/arfon/fidgit): | An ungodly union of GitHub and Figshare | Arfon Smith, Kaitlin Thaney, Mark Hahnel | Ruby | 0.1.0
[Software Heritage](https://docs.softwareheritage.org/devel/swh-indexer/metadata-workflow.html#adding-support-for-additional-ecosystem-specific-metadata)|The metadata indexers | SWH team | Python | 2.0
[Software Heritage](https://docs.softwareheritage.org/devel/swh-indexer/metadata-workflow.html#adding-support-for-additional-ecosystem-specific-metadata)|The metadata indexers | SWH team | Python | 2.0, 3.0


Pending:


- JOSS
- Zenodo
- DataCite
- Figshare


36 changes: 22 additions & 14 deletions content/user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,23 @@ You can use the [codemeta-generator](https://codemeta.github.io/codemeta-generat

A CodeMeta instance file describes the metadata associated with a software object using JSON's linked data (JSON-LD) notation. A codemeta file can contain any of the properties described on the [CodeMeta terms page](/terms/). Most codemeta files are called `codemeta.json` by convention.

Here is an example of a basic `codemeta.json` that you can put at the root of a Github repo ([link to full example](https://github.com/ropensci/codemetar/blob/master/codemeta.json)):
Here is an example of a basic `codemeta.json` that you can put at the root of a Github repo ([link to full example](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)):

```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
"@type": "SoftwareSourceCode",
"name": "CodemetaR",
"description": "Codemeta defines a 'JSON-LD' format for describing software metadata. This package provides utilities to generate, parse, and modify codemeta.jsonld files automatically for R packages.",
"license": "https://spdx.org/licenses/GPL-3.0",
"identifier": "http://dx.doi.org/10.5281/zenodo.XXXX"
"@context": "https://w3id.org/codemeta/3.0",
"type": "SoftwareSourceCode",
"applicationCategory": "Biology",
"codeRepository": "https://github.com/gem-pasteur/macsyfinder",
"description": "MacSyFinder is a program to model and detect macromolecular systems, genetic pathways… in prokaryotes protein datasets.",
"downloadUrl": "https://pypi.org/project/MacSyFinder/",
"license": "https://spdx.org/licenses/GPL-3.0+",
"name": "macsyfinder",
"version": "2.1.4",
"continuousIntegration": "https://github.com/gem-pasteur/macsyfinder/actions",
"developmentStatus": "active",
"issueTracker": "https://github.com/gem-pasteur/macsyfinder/issues",
"referencePublication": "https://doi.org/10.24072/pcjournal.250"
}
```

Expand Down Expand Up @@ -89,7 +97,7 @@ This should be added at the top level of the document, indicating that this indi

```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
"@context": "https://w3id.org/codemeta/3.0",
"@type": "SoftwareSourceCode",
"name": "CodemetaR",

Expand All @@ -108,7 +116,7 @@ JSON-LD operations can later *expand* this reference and *embed* the full inform

```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
"@context": "https://w3id.org/codemeta/3.0",
"@type": "SoftwareSourceCode",
"name": "CodemetaR",

Expand Down Expand Up @@ -136,7 +144,7 @@ We saw before a simple (root) SoftwareSourceCode object:

```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
"@context": "https://w3id.org/codemeta/3.0",
"@type": "SoftwareSourceCode",
"name": "CodemetaR"
}
Expand All @@ -146,7 +154,7 @@ and this root object can refer to other objects, for example recommend a Softwar

```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
"@context": "https://w3id.org/codemeta/3.0",
"@type": "SoftwareSourceCode",
"name": "CodemetaR",

Expand All @@ -161,7 +169,7 @@ And you may in turn want to add attributes to this application:

```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
"@context": "https://w3id.org/codemeta/3.0",
"@type": "SoftwareSourceCode",
"name": "CodemetaR",

Expand All @@ -183,7 +191,7 @@ For example, the above code is not equivalent to:

```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
"@context": "https://w3id.org/codemeta/3.0",
"@type": "SoftwareSourceCode",
"name": "CodemetaR",

Expand Down Expand Up @@ -213,7 +221,7 @@ appropriate context file, e.g.


```
"@context": "https://doi.org/10.5063/schema/codemeta-2.0"
"@context": "https://w3id.org/codemeta/3.0"
```

Release candidate versions may be referred to consistently using their git tag for the raw version, e.g. <https://raw.githubusercontent.com/codemeta/codemeta/2.0-rc/codemeta.jsonld>. *Please do not refer to the raw GitHub URL for the master branch*, as this is subject to change and will not guarantee a stable metadata file.
Expand Down