Skip to content

Update user-guide.md with JSON highlighting and etc. #49

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update user-guide.md with JSON highlighting and etc. #49

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
31 changes: 13 additions & 18 deletions content/user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ title: user guide

You can use the [codemeta-generator](https://codemeta.github.io/codemeta-generator/) directly at <https://codemeta.github.io/codemeta-generator/>

## Creating A CodeMeta Instance File Manually
## 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.

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/ropensci/codemetar/blob/master/codemeta.json)):
```json
{
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
Expand All @@ -27,7 +27,7 @@ Here is an example of a basic `codemeta.json` that you can put at the root of a

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:

```
```json
"name" : "R Interface to the DataONE REST API"
```

Expand All @@ -37,13 +37,13 @@ There must be a comma between of these key-value pairs, and no comma at the end

A JSON array is surrounded by the characters `[` and `]`, and can contain 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:

```
```json
"keywords": [
"data sharing",
"data repository",
Expand All @@ -53,9 +53,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:

```
```json
"license": [
"https://spdx.org/licenses/GPL-3.0",
"https://spdx.org/licenses/GPL-3.0-or-later",
"https://spdx.org/licenses/BSD-3-Clause"
]
```
Expand All @@ -64,7 +64,7 @@ All fields that accept a value of a given type accept an array of values of this

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:

```
```json
"author": {
"@id": "http://orcid.org/0000-0003-0077-4738",
"@type": "Person",
Expand All @@ -81,7 +81,7 @@ The [terms page](/terms/) indicates these node types.

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:

```
```json
"maintainer": "http://orcid.org/0000-0003-0077-4738"
```

Expand Down Expand Up @@ -129,7 +129,6 @@ JSON-LD operations can later *expand* this reference and *embed* the full inform
}
```


### Nesting objects

We saw before a simple (root) SoftwareSourceCode object:
Expand Down Expand Up @@ -203,23 +202,19 @@ because in the latter, `"https://cran.r-project.org"` is the `"url"` of `rmarkdo

## The 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 <http://schema.org>, but CodeMeta provides a few additional terms not found in <http://schema.org> which may be helpful for software projects. CodeMeta also restricts the context to use only those <https://schema.org> terms that are explicitly listed on ther [terms](/terms/) page. Users wanting to include additional terms must extend the context (see [developer-guide](/developer-guide/)).

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 <http://schema.org>, but CodeMeta provides a few additional terms not found in <http://schema.org> which may be helpful for software projects. CodeMeta also restricts the context to use only those <https://schema.org> terms that are explicitly listed on ther [terms](/terms/) page. Users wanting to include additional terms must extend the context (see [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.


```
```json
"@context": "https://doi.org/10.5063/schema/codemeta-2.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.


Release candidate versions may be referred to consistently using their [git tag](https://github.com/codemeta/codemeta/tags) 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.

## Testing An Instance file
## Testing an instance file

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".