diff --git a/content/user-guide.md b/content/user-guide.md index e344a7d..e64ad48 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -3,54 +3,82 @@ title: User Guide layout: sidenav --- -## Generating a CodeMeta file +## What are CodeMeta files? -You can use the [codemeta-generator](https://codemeta.github.io/codemeta-generator/) directly at +CodeMeta files, also called "CodeMeta instance files" are the `codemeta.json` +documents that are placed in the root of a software's code repository tree. +They define various aspects of the project in a JSON variant called JSON-LD, +which uses linking attributes to connect the data in this file with data from +other available sources. + +## The CodeMeta Generator + +The CodeMeta Generator is a tool for taking user input and either generating a +valid `codemeta.json` file, or testing an existing file to make sure that it +is valid. + +### Generating a CodeMeta instance file + +CodeMeta files can be generated using the +[CodeMeta Generator](https://codemeta.github.io/codemeta-generator/). +Instructions for [using the CodeMeta Generator](create) are available. + +A _*beta*_ version of an automatic generator is also linked on that page. + +Other utilities that can help with generating `codemeta.json` files are +listed on the [tools page](tools). + +### Testing a CodeMeta instance file + +Your CodeMeta files can be validated using the +[codemeta-generator](https://codemeta.github.io/codemeta-generator/). Paste +the contents of a `codemeta.json` file into the bottom box, and click the +`Validate codemeta.json` button. ## Creating a CodeMeta instance file manually -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. +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). -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)): +Any plaintext or code editor is sufficient for creating a CodeMeta instance +file. An editor that has syntax highlighting for `JSON` can assist by +making errors in the syntax stand out. -```json -{ - "@context": "https://w3id.org/codemeta/3.1", - "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" -} -``` +Most CodeMeta files are called `codemeta.json` by convention. While other +filenames are valid, they will be less recognisable and may be overlooked. +{.tip} + +### Understanding JSON and JSON-LD -### Basics +CodeMeta files contain JSON *key-value pairs*, sometimes referred to as +*name-value pairs* where the values can be *simple values*, *arrays*, or *JSON +objects*. Keys are also known as *properties* in linked data. -When creating a CodeMeta document, note that they contain JSON name ("property" in linked-data), value pairs where the values can be simple values, arrays or JSON objects. A simple value is a number, string, or one the literal values *false*, *null* *true*, for example: +#### Simple Values + +A simple value is a number, string, or one the literal values *false*, *null* +*true*. For example: ```json "name" : "R Interface to the DataONE REST API" ``` -There must be a comma between of these key-value pairs, and no comma at the end before the closing bracket (`}`). +Key-value pairs must be separated by a comma. There must be no comma at the +end before the closing brace (`}`). -### Arrays +#### Arrays -A JSON array is surrounded by the characters `[` and `]`, and can contain multiple values separated by commas: +A JSON array is surrounded by parentheses; `[` and `]`. Arrays can contain +one or multiple values separated by commas: ```json "keywords": [ "data sharing", "data repository", "DataONE" ] ``` -As with any JSON documents, you can add line breaks between values for improved quality. For example, the former key-value pair is this is equivalent to: +Arrays should contain line breaks between values and indenting (spaces at the +start of a line). These make the data easier for humans to read. The above +example is equivalent to: ```json "keywords": [ @@ -60,7 +88,9 @@ As with any JSON documents, you can add line breaks between values for improved ] ``` -All fields that accept a value of a given type accept an array of values of this type, and vice-versa. For example, a software with two licenses could have this attribute: +Fields that accept a value of a given type will accept an array of values of +that type. For example, a software with two licenses could have this +attribute: ```json "license": [ @@ -69,9 +99,11 @@ All fields that accept a value of a given type accept an array of values of this ] ``` -### Objects +#### Objects -Some properties, such as `author`, can refer to other JSON objects surrounded by curly braces and can contain other JSON values or objects, for example: +Some properties, such as `author`, can refer to other JSON objects. Objects +are surrounded by braces; `{` and `}`. These can contain other JSON values or +objects. For example: ```json "author": { @@ -83,18 +115,38 @@ Some properties, such as `author`, can refer to other JSON objects surrounded by } ``` -The JSON-LD "@type" keyword associates a JSON value or object with a well known type, for example, the -statement `"@type":"Person"` associates the `author` object with `http://schema.org/Person`. -It is good practice to always provide the `@type` for any property which specifies a node (JSON object). -The [terms page](/terms/) indicates these node types. +#### Keywords + +JSON-LD has the concept of Keywords, which are properties prefaced with a `@`. +Keywords give instructions to the processor instead of describing relations +between entities. + +This includes: + +* defining shorthands (`@context`, `@vocab`), +* changing value semantics (`@list` and `@set`, `@value`, `@language`, ...), +* intrinsically describing objects (`@id` and `@type`) + +The JSON-LD `@type` keyword associates a JSON value or object with a well +known type. In the previous example, the statement `"@type":"Person"` +associates the `author` object with `http://schema.org/Person`. The +`@type` for any property which specifies a node (JSON object) should be +provided. The `Type` column of [the terms page](/terms/) indicates the +options appropriate for each term. -The "author" JSON object illustrates the use of the JSON-LD keyword "@id", which is used to associate an IRI with the JSON object. Any such node object can be assigned an `@id`, and we may use the `@id` to refer to this same object (the person, Peter), elsewhere in the document; e.g. we can indicate the same individual is also the `maintainer` by adding: +The `author` JSON object illustrates the use of the JSON-LD keyword `@id`, +which is used to associate an IRI with the JSON object. Any such node object +can be assigned an `@id`, and future uses of the `@id` property's *value* will +refer to this same object, (the person, Peter), elsewhere in the document. For +example, we can indicate the same individual is also the `maintainer` by +adding: ```json "maintainer": "http://orcid.org/0000-0003-0077-4738" ``` -This should be added at the top level of the document, indicating that this individual is the `maintainer` of the software being described, like this: +This should be added at the top level of the document, indicating that this +individual is the `maintainer` of the software being described, like this: ```json { @@ -113,7 +165,11 @@ This should be added at the top level of the document, indicating that this indi } ``` -JSON-LD operations can later *expand* this reference and *embed* the full information at both locations. This means the example above is equivalent to: +JSON-LD operations can later *expand* this reference and *embed* the full +information at both locations. + +This means the previous example is equivalent to: + ```json { @@ -138,9 +194,10 @@ JSON-LD operations can later *expand* this reference and *embed* the full inform } ``` -### Nesting objects +#### Nesting objects -We saw before a simple (root) SoftwareSourceCode object: +The following SoftwareSourceCode object is an example of a simple root +object: ```json { @@ -150,7 +207,8 @@ We saw before a simple (root) SoftwareSourceCode object: } ``` -and this root object can refer to other objects, for example recommend a SoftwareApplication: +A root object can refer to other objects. For example, it may recommend a +SoftwareApplication: ```json { @@ -165,7 +223,8 @@ and this root object can refer to other objects, for example recommend a Softwar } ``` -And you may in turn want to add attributes to this application: +Nesting can go many layers deep. In this example, to add attributes to this +application: ```json { @@ -185,9 +244,22 @@ And you may in turn want to add attributes to this application: } ``` -It is important to mind the order of curly brackets (an object begins with a `{` and ends with a matching `}`) and indentation (spaces at the beginning of a line) to reflect the hierarchy: "Central R Archive Network (CRAN)" is the name of the provider of "rmarkdown", which is a softwareSuggestions of CodemetaR. +Indentation and matching braces are important. These reflect the hierarchy of +the document. + +Each object begins with a `{` and ends with a matching `}`. Each object should +also have a depth of indentation (the spaces at the beginning of a line) that +reflects its place in the hierarchy. + +This above example defines "Central R Archive Network (CRAN)" as the name of +the provider of "rmarkdown", which is a softwareSuggestions of CodemetaR. -For example, the above code is not equivalent to: +Putting key-value or property-value pairs in a different place in the document +hierarchy can change the meaning of the document. + +The code below has the `"url"` pair at a different hierarchy. The result is +that it no longer belongs with the `"provider"` information, and the meaning +of the document has changed. It is *_not_* equivalent to the code above. ```json { @@ -207,23 +279,247 @@ For example, the above code is not equivalent to: } ``` -because in the latter, `"https://cran.r-project.org"` is the `"url"` of `rmarkdown`, instead of being the url of `Central R Archive Network (CRAN)`. +The change in hierarchy means that `"https://cran.r-project.org"` is +represented as the `"url"` of `rmarkdown`, instead of being the url of +`Central R Archive Network (CRAN)`. + +## Context + +Every CodeMeta document must refer to the context file `codemeta.jsonld`, for +example via a URL. This indicates that all terms in the document should be +interpreted in the "context" of CodeMeta. + +Most terms are chosen to match the equivalent terms in , +but CodeMeta provides a few additional terms not found in +which may be helpful for software projects. -## The context +CodeMeta also restricts the context to use only those +terms that are explicitly listed on the [terms](/terms/) page. Users wanting +to include additional terms may: -Every CodeMeta document must refer to the context file *codemeta.jsonld*, for example via a URL. This indicates that all terms in the document should be interpreted in the "context" of CodeMeta. Most terms are chosen to match the equivalent terms in , but CodeMeta provides a few additional terms not found in which may be helpful for software projects. CodeMeta also restricts the context to use only those terms that are explicitly listed on the [terms](/terms/) page. Users wanting to include additional terms must extend the context (see [developer-guide](/developer-guide/)). +* Use the `schema:` prefix to define them as terms, (such +as `"schema:releaseNotes"` [in this example](https://github.com/SciCodes/somef-core/blob/f0481b6f28166e1c5a95919d2767f1aaa5b3fa87/codemeta.json#L85)), or +* Extend the context (see [the developer guide](/developer-guide/)). -The context file may be modified and updated in the future, if new JSON properties are added or existing ones modified. -The CodeMeta GitHub repository defines tags to allow specific versions of a file to be referenced, and assigns -*digital object identifiers*, or DOIs, to each release tag. Please use the [appropriate release](https://github.com/codemeta/codemeta/releases) of the CodeMeta schema in order to refer to the -appropriate context file, e.g. +The context file may be modified and updated in the future, if new JSON +properties are added or existing ones modified. + +The CodeMeta GitHub repository [defines tags](https://github.com/codemeta/codemeta/tags) +to allow specific versions of a file to be referenced, and assigns permanant +identifiers for each release tag. Early releases used Digital Object +Identifiers (DOIs), and recent releases use W3IDs. Please use the +[appropriate release](https://github.com/codemeta/codemeta/releases) +of the CodeMeta schema in order to refer to the appropriate context file. + +For example, use the following for the latest release: ```json "@context": "https://w3id.org/codemeta/3.1" ``` -Release candidate versions may be referred to consistently using their [git tag](https://github.com/codemeta/codemeta/tags) for the raw version, e.g. . *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. +## Attributions + +Giving attribution to people and organizations who have made a software +application is a large part of many `codemeta.json` files, especially if +projects involve a community. + +It is important to give proper attribution to the contributions that have been +made. This includes using stable identifiers where possible and meaningful +descriptions of each party's participation. + +This is done primarily with the use of `Person`, `Role`, and `Organization` +properties types. + +### People + +The properties listed in the [terms](terms) tables with a type `Person` +can list one or more objects of the `Person` type that describe the various +individuals who made the software. They have the `@type` or `type` value of +`Person`. + +They are top-level properties and should, where possible, contain an `@id` +value that consistently identifies the individual and can be used for +JSON-LD linking operations. + +The distinction between an `author` and a `contributor` is not strictly +defined and each project can assign it according to their preference. The +properties describe a `contributor` as someone considered a "secondary +contributor", perhaps to be reserved for non-code contributions. + +A `maintainer` should include a method of contact, such as an email address. + +Applications with one `author` may list the individual values directly within +the `author` object. For example: + +```json +"author": { + "id": "http://orcid.org/0000-0003-0077-4738", + "@type": "Person", + "email": "slaughter@nceas.ucsb.edu", + "givenName": "Peter", + "familyName": "Slaughter" +} +``` + +Applications with multiple `author` individuals must describe them within an +array (`[`, `]`) of objects, as follows: + +```json +"author": [ + { + "id": "https://orcid.org/0000-0002-1825-0097", + "type": "Person", + "affiliation": { + "type": "Organization", + "name": "Institut Pasteur, Université Paris Cité, Bioinformatics and Biostatistics HUB, Paris, France " + }, + "email": "bneron@pasteur.fr", + "familyName": "Néron", + "givenName": "Bertrand" + }, + { + "id": "https://orcid.org/0000-0002-2771-9344", + "type": "Person", + "affiliation": { + "type": "Organization", + "name": " Univ. Grenoble Alpes, CNRS, UMR 5525, VetAgro Sup, Grenoble INP, TIMC, 38000 Grenoble, France " + }, + "email": "sophie.abby@univ-grenoble-alpes.fr", + "familyName": "Abby", + "givenName": "Sophie" + }, +... +] +``` + +The specific values of the properties, such as `familyName` and `givenName` +are free-form, and often contain pseudonyms or group names. `codemeta.json` +files with such values are still valid, but where possible the values should +refer to a consistent identity of an individual. + +### Roles + +The `Role` type property is used within the `author` or `contributor` +properties to further define the participation of a `Person`. The property is +intended to clarify the functional area the individual with the free-form +value of the `roleName` property. + +An example author role: + +```json +"author": [ +... + { + "roleName": "User Experience Design", + "schema:author": "https://github.com/octocat", + "type": "Role" + }, +... +] +``` + +Or a contributor: + +```json +"contributor": [ +... + { + "roleName": "Documentation", + "schema:author": "https://github.com/octocat", + "type": "Role" + }, +... +] +``` + +This is distinct from the `maintainer` property, which should be defined +independently as a top-level property of the document, containing at least +one `Person`. + +The `Role` must link to a `Person` previously defined in the top-level +property. The example below demonstrates the `id` and `schema:author` values +providing this link. + +```json +"author": [ + { + "familyName": "Mannem", + "id": "https://github.com/ruthvikm", + "givenName": "Ruthvik", + "type": "Person" + }, +... + { + "roleName": "Tech Lead", + "schema:author": "https://github.com/ruthvikm", + "type": "Role" + }, +... +] + +``` + +[Full example](https://github.com/oss-slu/Pi4Micronaut/blob/de4305bec9afe7f7c948e9cc97b9105fd55121f7/codemeta.json). + +### Organizations + +The properties listed in the [terms](terms) tables with a type `Organization` +can list one or more organizations. They have the `type` value of +`Organization`. + +The `affiliation` property within a `Person` property is a common example of +this object type. `affiliation` defines the associations that the individual +has with various organizations. Like the `author` property, the properties +can contain values, or an array of objects with those same values for multiple +affiliations. + +The [second example in the "People" section](user-guide/#people) contains a +use of the affiliation property, with `Organization` as its type. + +## Describing the Software + +A minimum viable CodeMeta file needs only a `@context`, a `type` and a `name`. +While valid, this is not a useful description of the software. + +Each project's `codemeta.json` should represent that project's lifecycle, +resources, and people. It should be considered a living document. Properties +representing dynamic information such as `version` and `authors` should be +updated as the software changes for the document to be most useful. + +Useful properties include the ones in the example in the next section. Refer +to the [terms](terms) page for all CodeMeta properties. + +## Example of a CodeMeta file + +The following is an example of a basic `codemeta.json` that can be put at the +root of a code repository: + +```json +{ + "@context": "https://w3id.org/codemeta/3.1", + "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" +} +``` + +([Link to full example](https://github.com/gem-pasteur/macsyfinder/blob/69c22b065065105e6c5ac8dcbff00a804a0a34fc/codemeta.json)). + +## Referencing CodeMeta -## Testing An Instance file +All versions, including release candidates, may be referred to consistently +using their [git tag](https://github.com/codemeta/codemeta/tags) for the raw +version, e.g. . -Our [codemeta-generator](https://codemeta.github.io/codemeta-generator/) can also check a codemeta.json file you wrote is valid. To do that, copy-paste your code in the bottom box, and click "Validate codemeta.json". +*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. +{.warning} diff --git a/themes/CodeMeta-Pyramids/static/css/codemeta.css b/themes/CodeMeta-Pyramids/static/css/codemeta.css index b5d1f96..855fe3f 100644 --- a/themes/CodeMeta-Pyramids/static/css/codemeta.css +++ b/themes/CodeMeta-Pyramids/static/css/codemeta.css @@ -78,9 +78,14 @@ div.highlight { background-color: var(--bs-tertiary-bg); } +.highlight pre { + text-wrap-mode: wrap; +} + [data-bs-theme=dark] div.highlight { border: 1px solid var(--bs-body-bg); padding: 10px 10px 0px 10px; + margin: 25px 0px; } [data-bs-theme=dark] .highlight { @@ -316,3 +321,47 @@ code{ dl, li { font-size: 14px; } + +p img { + margin: 25px 0px; +} + +/*! + * infobox paragraphs and blockquotes + */ + +p.tip, p.warning, p.danger, blockquote{ + background-repeat: no-repeat; + background-size: 30px; + background-position: 10px 50%; + padding: 10px 10px 10px 60px; + min-height: 30px; +} + +p.tip, p.warning, p.danger, blockquote { + background-color: var(--bs-secondary-bg); + border-left: 3px; + fill: currentcolor; +} + +[data-bs-theme=dark] blockquote, [data-bs-theme=dark] p.tip, [data-bs-theme=dark] p.warning, [data-bs-theme=dark] p.danger{ + background-color: var(--bs-border-color) !important; + color: var(--bs-body-color); + border-radius: 5px; +} + +blockquote { + background-image: url('data:image/svg+xml,') +} + +p.tip, blockquote.tip { + background-image: url('data:image/svg+xml,'); +} + +p.warning, blockquote.warning { + background-image: url('data:image/svg+xml,'); +} + +p.danger, blockquote.danger { + background-image: url('data:image/svg+xml,'); +}