Generate 'CodeMeta' Metadata for R Packages

The 'Codemeta' Project defines a 'JSON-LD' format for describing software metadata, as detailed at < https://codemeta.github.io>. This package provides utilities to generate, parse, and modify 'codemeta.json' files automatically for R packages, as well as tools and examples for working with 'codemeta.json' 'JSON-LD' more generally.


Project Status: Active – The project has reached a stable, usablestate and is being activelydeveloped. Travis-CI BuildStatus AppVeyor Buildstatus CoverageStatus CRAN_Status_Badge DOI downloads

The goal of codemetar is to generate the JSON-LD file, codemeta.json containing software metadata describing an R package. For more general information about the CodeMeta Project for defining software metadata, see https://codemeta.github.io. In particular, new users might want to start with the User Guide, while those looking to learn more about JSON-LD and consuming existing codemeta files should see the Developer Guide.

Installation

You can install the latest version from CRAN using:

install.packages("codemetar")

You can also install the development version of codemetar from github with:

# install.packages("devtools")
devtools::install_github("ropensci/codemetar")
library("codemetar")

Example

This is a basic example which shows you how to generate a codemeta.json for an R package (e.g. for testthat):

write_codemeta("testthat")

codemetar can take the path to the package root instead. This may allow codemetar to glean some additional information that is not available from the description file alone.

write_codemeta(".")

Which creates a file looking like so (first 10 lines; see full codemeta.json here):

{
  "@context": [
    "https://doi.org/10.5063/schema/codemeta-2.0",
    "http://schema.org"
  ],
  "@type": "SoftwareSourceCode",
  "identifier": "codemetar",
  "description": "The 'Codemeta' Project defines a 'JSON-LD' format for describing\n  software metadata, as detailed at <https://codemeta.github.io>. This package\n  provides utilities to generate, parse, and modify 'codemeta.json' files \n  automatically for R packages, as well as tools and examples for working with\n  'codemeta.json' 'JSON-LD' more generally.",
  "name": "codemetar: Generate 'CodeMeta' Metadata for R Packages",
  "codeRepository": "https://github.com/ropensci/codemetar",

Modifying or enriching CodeMeta metadata

The best way to ensure codemeta.json is as complete as possible is to begin by making full use of the fields that can be set in an R package DESCRIPTION file, such as BugReports and URL. Using the [email protected] notation allows a much richer specification of author roles, correct parsing of given vs family names, and email addresses.

In the current implementation, developers may specify an ORCID url for an author in the optional comment field of [email protected], e.g.

[email protected]: person("Carl", "Boettiger", role=c("aut", "cre", "cph"), email="[email protected]", comment="http://orcid.org/0000-0002-1642-628X")

which will allow codemetar to associate an identifier with the person. If the package is hosted on CRAN, including the ORCiD in this way will cause an ORCiD logo and link to the ORCiD page to be added to the package CRAN webpage.

Using the DESCRIPTION file

The DESCRIPTION file is the natural place to specify any metadata for an R package. The codemetar package can detect certain additional terms in the CodeMeta context. Almost any additional codemeta field (see codemetar:::additional_codemeta_terms for a list) and can be added to and read from the DESCRIPTION into a codemeta.json file.

CRAN requires that you prefix any additional such terms to indicate the use of schema.org explicitly, e.g. keywords would be specified in a DESCRIPTION file as:

X-schema.org-keywords: metadata, codemeta, ropensci, citation, credit, linked-data

Where applicable, these will override values otherwise guessed from the source repository. Use comma-separated lists to separate multiple values to a property, e.g. keywords.

See the DESCRIPTION file of the codemetar package for an example.

Going further

Check out all the codemetar vignettes for tutorials on other cool stuff you can do with codemeta and json-ld.

ropensci_footer

News

codemetar 0.1.7 2018-12

  • jsonld that is used only in crosswalk() and codemeta_validate() is now an optional dependency (Suggests rather than Imports).

  • The CodeRepository URL is now cleaned a bit (removing direct link to the README).

  • write_codemeta() gains a new argument use_githook to make the creation of a DESCRIPTION/codemeta.json git pre-commit hook optional.

  • create_codemeta() and write_codemeta() gain a new argument use_filesize to make the building of the package to get its size optional.

  • Encoding bug fixed in extract_badges().

  • extract_badges() now uses commonmark and xml2 instead of only regular expressions.

  • pkgbuild is now used directly instead of devtools.

  • give_opinion() now recognizes lifecycle badges, not only repostatus.org badges.

codemetar 0.1.6 2018-04

  • New functions

    • extract_badges for extracting information from all badges in a Markdown file.

    • give_opinion giving opiniated advice about package metadata

  • Changes to the create_codemeta output

    • relatedLink field now include provider URL and URL(s) from DESCRIPTION that are not the code repository

    • maintainer is now a list allowing for several maintainers since e.g. the BioConductor a4 package has two maintainers.

    • if more than one CI service among Travis, Appveyor and Circle CI are used and shown via a README badge they're all added to the contIntegration field. URLs from codecov and coveralls badges are also added to the contIntegration field.

    • repo status inferred from the README now 1) is an URL instead of a word 2) recognizes either repostatus.org or Tidyverse lifecycle badges.

    • if present, priority is given to the Repository and BugReports fields of DESCRIPTION for filling the codeRepository and issueTracker fields of codemeta.json (which means working on a fork won't change these).

    • ability to parse all CRAN-allowed MARC roles.

    • if there is a badge for an rOpenSci onboarding review and the review issue is closed, basic review metadata is added to codemeta.json

    • For dependencies, if the provider guessed is CRAN or BioConductor, their canonic CRAN/BioConductor URL is added to codemeta.json as sameAs, unless there's a GitHub repo mentioned for them in Remotes in DESCRIPTION, in which case sameAs is that GitHub repo.

    • CRAN is now correctly translated as "Comprehensive R Archive Network"

    • If codeRepository is guessed to be a GitHub repo (via the URL field of DESCRIPTION or via git remote URL), the repo topics are queried via GitHub API V3 and added to the keywords (in combination with keywords stored in the X-schema.org-keywords field of DESCRIPTION)

    • SystemRequirements are now parsed using https://sysreqs.r-hub.io/, outputting URLs then stored in softwareRequirements

  • Help to remind to update codemeta.json regularly: Writing codemeta.json for the first time adds a git pre-commit hook and suggests adding a release question for devtools::release.

  • Internal changes

    • Now uses desc to parse DESCRIPTION files.

    • Package license changed to GPL because of code borrowed from usethis

    • Uses crul instead of httr and uses crul to check some URLs.

    • write_codemeta only uses Rbuildignore and a pre-commit git hook if the function is called from a package folder directly and with the path argument equal to "codemeta.json"

    • The calls to available.packages() for guess_provider now happen inside memoised functions.

    • codemeta_readme function.

codemetar 0.1.5 2018-03-21

  • Default to DOI-based schema. (previous CN issues now resolved)

codemetar 0.1.4 2018-02-12

  • Allow vignettes to gracefully handle network timeout errors that may occur on CRAN's Windows build server.

codemetar 0.1.3 2018-02-08

  • CRAN release
  • Switch to http://purl.org based URIs for the JSON-LD Context file instead of a DOI, due to frequent failure of content negotiation on DataCite servers (#34)
  • bugfix UTF-8 characters in CITATION files (#44)
  • bugfix to git URLs
  • Use https on ORCID @id URIs

codemetar 0.1.2

  • JOSS release

codemetar 0.1.1

  • Post onboarding release

codemetar 0.1.0

  • Added a NEWS.md file to track changes to the package.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("codemetar")

0.1.7 by Carl Boettiger, a month ago


https://github.com/ropensci/codemetar, https://ropensci.github.io/codemetar


Report a bug at https://github.com/ropensci/codemetar/issues


Browse source code at https://github.com/cran/codemetar


Authors: Carl Boettiger [aut, cre, cph] , Anna Krystalli [rev, ctb] , Toph Allen [rev] , Maëlle Salmon [ctb, aut] , rOpenSci [fnd] (https://ropensci.org/) , Katrin Leinweber [ctb] , Noam Ross [ctb] , Arfon Smith [ctb] , Jeroen Ooms [ctb] , Sebastian Meyer [ctb] , Michael Rustler [ctb] , Hauke Sonnenberg [ctb]


Documentation:   PDF Manual  


GPL-3 license


Imports jsonlite, git2r, pkgbuild, memoise, methods, stats, stringi, readr, desc, usethis, whisker, tibble, crul, gh, stringr, sessioninfo, purrr, curl, commonmark, xml2, magrittr, glue

Suggests testthat, jsonld, jsonvalidate, covr, knitr, rmarkdown, dplyr, printr


See at CRAN