Skip to content

Commit 8e8f7e7

Browse files
meldrameldra
committed
Rearrange and rewrite parts of the userguide
1 parent c93fbb6 commit 8e8f7e7

File tree

2 files changed

+487
-53
lines changed

2 files changed

+487
-53
lines changed

‎content/user-guide.md‎

Lines changed: 174 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -3,54 +3,80 @@ title: User Guide
33
layout: sidenav
44
---
55

6-
## Generating a CodeMeta file
6+
## What are CodeMeta files?
77

8-
You can use the [codemeta-generator](https://codemeta.github.io/codemeta-generator/) directly at <https://codemeta.github.io/codemeta-generator/>
8+
CodeMeta files, also called "CodeMeta instance files" are the `codemeta.json`
9+
documents that are placed in the root of a software's code repository tree.
10+
They define various aspects of the project in a JSON variant called JSON-LD,
11+
which uses linking attributes to connect the data in this file with data from
12+
other available sources.
13+
14+
## The CodeMeta Generator
15+
16+
The CodeMeta Generator is a tool for taking user input and either generating a
17+
valid `codemeta.json` file, or testing an existing file to make sure that it
18+
is valid.
19+
20+
### Generating a CodeMeta instance file
21+
22+
CodeMeta files can be generated using the
23+
[CodeMeta Generator](https://codemeta.github.io/codemeta-generator/).
24+
Instructions for [using the CodeMeta Generator](create) are available.
25+
26+
A _*beta*_ version of an automatic generator is also linked on that page.
27+
28+
### Testing a CodeMeta instance file
29+
30+
Your CodeMeta files can be validated using the
31+
[codemeta-generator](https://codemeta.github.io/codemeta-generator/). Paste
32+
the contents of a `codemeta.json` file into the bottom box, and click the
33+
`Validate codemeta.json` button.
934

1035
## Creating a CodeMeta instance file manually
1136

12-
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.
37+
A CodeMeta instance file describes the metadata associated with a software
38+
object using JSON's linked data (JSON-LD) notation. A CodeMeta file can
39+
contain any of the properties described on the [CodeMeta terms page](terms).
1340

14-
Here is an example of a basic `codemeta.json` that you can put at the root of a GitHub repo
15-
([link to full example](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)):
41+
Any plaintext or code editor is sufficient for creating a CodeMeta instance
42+
file. An editor that has syntax highlighting for `JSON` can assist by
43+
making errors in the syntax stand out.
1644

17-
```json
18-
{
19-
"@context": "https://w3id.org/codemeta/3.1",
20-
"type": "SoftwareSourceCode",
21-
"applicationCategory": "Biology",
22-
"codeRepository": "https://github.com/gem-pasteur/macsyfinder",
23-
"description": "MacSyFinder is a program to model and detect macromolecular systems, genetic pathways… in prokaryotes protein datasets.",
24-
"downloadUrl": "https://pypi.org/project/MacSyFinder/",
25-
"license": "https://spdx.org/licenses/GPL-3.0+",
26-
"name": "macsyfinder",
27-
"version": "2.1.4",
28-
"continuousIntegration": "https://github.com/gem-pasteur/macsyfinder/actions",
29-
"developmentStatus": "active",
30-
"issueTracker": "https://github.com/gem-pasteur/macsyfinder/issues",
31-
"referencePublication": "https://doi.org/10.24072/pcjournal.250"
32-
}
33-
```
45+
Most CodeMeta files are called `codemeta.json` by convention. While other
46+
filenames are valid, they will be less recognisable and may be overlooked.
47+
{.tip}
48+
49+
### Understanding JSON and JSON-LD
3450

35-
### Basics
51+
CodeMeta files contain JSON *key-value pairs*, sometimes referred to as
52+
*name-value pairs* where the values can be *simple values*, *arrays*, or *JSON
53+
objects*. Key-value pairs are known as *property-value pairs* in JSON-LD
54+
linked-data.
3655

37-
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:
56+
#### Simple Values
57+
58+
A simple value is a number, string, or one the literal values *false*, *null*
59+
*true*. For example:
3860

3961
```json
4062
"name" : "R Interface to the DataONE REST API"
4163
```
4264

43-
There must be a comma between of these key-value pairs, and no comma at the end before the closing bracket (`}`).
65+
Key-value pairs must be separated by a comma. There must be no comma at the
66+
end before the closing brace (`}`).
4467

45-
### Arrays
68+
#### Arrays
4669

47-
A JSON array is surrounded by the characters `[` and `]`, and can contain multiple values separated by commas:
70+
A JSON array is surrounded by parentheses; `[` and `]`. Arrays can contain
71+
one or multiple values separated by commas:
4872

4973
```json
5074
"keywords": [ "data sharing", "data repository", "DataONE" ]
5175
```
5276

53-
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:
77+
Arrays should contain line breaks between values and indenting (spaces at the
78+
start of a line). These make the data easier for humans to read. The above
79+
example is equivalent to:
5480

5581
```json
5682
"keywords": [
@@ -60,7 +86,9 @@ As with any JSON documents, you can add line breaks between values for improved
6086
]
6187
```
6288

63-
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:
89+
Fields that accept a value of a given type will accept an array of values of
90+
that type. For example, a software with two licenses could have this
91+
attribute:
6492

6593
```json
6694
"license": [
@@ -69,9 +97,11 @@ All fields that accept a value of a given type accept an array of values of this
6997
]
7098
```
7199

72-
### Objects
100+
#### Objects
73101

74-
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:
102+
Some properties, such as `author`, can refer to other JSON objects. Objects
103+
are surrounded by braces; `{` and `}`. These can contain other JSON values or
104+
objects. For example:
75105

76106
```json
77107
"author": {
@@ -83,18 +113,44 @@ Some properties, such as `author`, can refer to other JSON objects surrounded by
83113
}
84114
```
85115

86-
The JSON-LD "@type" keyword associates a JSON value or object with a well known type, for example, the
87-
statement `"@type":"Person"` associates the `author` object with `http://schema.org/Person`.
88-
It is good practice to always provide the `@type` for any property which specifies a node (JSON object).
89-
The [terms page](/terms/) indicates these node types.
116+
#### Keywords
117+
118+
JSON-LD has the concept of Keywords, which are properties prefaced with a `@`.
119+
120+
These references work similar to includes in a programming language.
121+
{.tip}
122+
123+
Keywords are instructions for the processor of the file to refer to
124+
previously stored information. This means that the exact same information can
125+
be included multiple times, and pulled from a consistent source.
126+
127+
The source can be an external resource, as depicted in the diagram below:
128+
129+
![Diagram of a JSON-LD reference pulling data in from an external data source](/img/jsonld-references-diagram.svg)
90130

91-
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:
131+
The JSON-LD "@type" keyword associates a JSON value or object with a well
132+
known type. In the previous example, the statement `"@type":"Person"`
133+
associates the `author` object with `http://schema.org/Person`. It is good
134+
practice to always provide the `@type` for any property which specifies a node
135+
(JSON object). The [terms page](/terms/) indicates these node types.
136+
137+
Keywords also provide similiar utility to a function in a programming
138+
language; they prompt the processor to output the same data in another place
139+
in the file.
140+
{.tip}
141+
142+
The "author" JSON object illustrates the use of the JSON-LD keyword "@id",
143+
which is used to associate an IRI with the JSON object. Any such node object
144+
can be assigned an `@id`, and we may use the `@id` to refer to this same
145+
object (the person, Peter), elsewhere in the document; e.g. we can indicate
146+
the same individual is also the `maintainer` by adding:
92147

93148
```json
94149
"maintainer": "http://orcid.org/0000-0003-0077-4738"
95150
```
96151

97-
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:
152+
This should be added at the top level of the document, indicating that this
153+
individual is the `maintainer` of the software being described, like this:
98154

99155
```json
100156
{
@@ -113,7 +169,12 @@ This should be added at the top level of the document, indicating that this indi
113169
}
114170
```
115171

116-
JSON-LD operations can later *expand* this reference and *embed* the full information at both locations. This means the example above is equivalent to:
172+
173+
JSON-LD operations can later *expand* this reference and *embed* the full
174+
information at both locations.
175+
176+
This means the previous example is equivalent to:
177+
117178

118179
```json
119180
{
@@ -138,9 +199,10 @@ JSON-LD operations can later *expand* this reference and *embed* the full inform
138199
}
139200
```
140201

141-
### Nesting objects
202+
#### Nesting objects
142203

143-
We saw before a simple (root) SoftwareSourceCode object:
204+
The following SoftwareSourceCode object is an example of a simple root
205+
object:
144206

145207
```json
146208
{
@@ -150,7 +212,8 @@ We saw before a simple (root) SoftwareSourceCode object:
150212
}
151213
```
152214

153-
and this root object can refer to other objects, for example recommend a SoftwareApplication:
215+
A root object can refer to other objects. For example, it may recommend a
216+
SoftwareApplication:
154217

155218
```json
156219
{
@@ -165,7 +228,8 @@ and this root object can refer to other objects, for example recommend a Softwar
165228
}
166229
```
167230

168-
And you may in turn want to add attributes to this application:
231+
Nesting can go many layers deep. In this example, to add attributes to this
232+
application:
169233

170234
```json
171235
{
@@ -185,9 +249,22 @@ And you may in turn want to add attributes to this application:
185249
}
186250
```
187251

188-
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.
252+
Indentation and matching braces are important. These reflect the hierarchy of
253+
the document.
254+
255+
Each object begins with a `{` and ends with a matching `}`. Each object should
256+
also have a depth of indentation (the spaces at the beginning of a line) that
257+
reflects its place in the hierarchy.
258+
259+
This above example defines "Central R Archive Network (CRAN)" as the name of
260+
the provider of "rmarkdown", which is a softwareSuggestions of CodemetaR.
261+
262+
Putting key-value or property-value pairs in a different place in the document
263+
hierarchy can change the meaning of the document.
189264

190-
For example, the above code is not equivalent to:
265+
The code below has the `"url"` pair at a different hierarchy. The result is
266+
that it no longer belongs with the `"provider"` information, and the meaning
267+
of the document has changed. It is *_not_* equivalent to the code above.
191268

192269
```json
193270
{
@@ -207,23 +284,67 @@ For example, the above code is not equivalent to:
207284
}
208285
```
209286

210-
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)`.
287+
The change in hierarchy means that `"https://cran.r-project.org"` is
288+
represented as the `"url"` of `rmarkdown`, instead of being the url of
289+
`Central R Archive Network (CRAN)`.
290+
291+
### Example of a CodeMeta file
292+
293+
The following is an example of a basic `codemeta.json` that can be put at the
294+
root of a code repository.
295+
([link to full example](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)):
296+
297+
```json
298+
{
299+
"@context": "https://w3id.org/codemeta/3.1",
300+
"type": "SoftwareSourceCode",
301+
"applicationCategory": "Biology",
302+
"codeRepository": "https://github.com/gem-pasteur/macsyfinder",
303+
"description": "MacSyFinder is a program to model and detect macromolecular systems, genetic pathways… in prokaryotes protein datasets.",
304+
"downloadUrl": "https://pypi.org/project/MacSyFinder/",
305+
"license": "https://spdx.org/licenses/GPL-3.0+",
306+
"name": "macsyfinder",
307+
"version": "2.1.4",
308+
"continuousIntegration": "https://github.com/gem-pasteur/macsyfinder/actions",
309+
"developmentStatus": "active",
310+
"issueTracker": "https://github.com/gem-pasteur/macsyfinder/issues",
311+
"referencePublication": "https://doi.org/10.24072/pcjournal.250"
312+
}
313+
```
211314

212315
## The context
213316

214-
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 the [terms](/terms/) page. Users wanting to include additional terms must extend the context (see [developer-guide](/developer-guide/)).
317+
Every CodeMeta document must refer to the context file *codemeta.jsonld*, for
318+
example via a URL. This indicates that all terms in the document should be
319+
interpreted in the "context" of CodeMeta.
320+
321+
Most terms are chosen to match the equivalent terms in <http://schema.org>,
322+
but CodeMeta provides a few additional terms not found in <http://schema.org>
323+
which may be helpful for software projects.
324+
325+
CodeMeta also restricts the context to use only those <https://schema.org>
326+
terms that are explicitly listed on the [terms](/terms/) page. Users wanting
327+
to include additional terms must extend the context (see
328+
[the developer guide](/developer-guide/)).
329+
330+
The context file may be modified and updated in the future, if new JSON
331+
properties are added or existing ones modified.
215332

216-
The context file may be modified and updated in the future, if new JSON properties are added or existing ones modified.
217-
The CodeMeta GitHub repository defines tags to allow specific versions of a file to be referenced, and assigns
218-
*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
219-
appropriate context file, e.g.
333+
The CodeMeta GitHub repository defines tags to allow specific versions of a
334+
file to be referenced, and assigns *digital object identifiers*, or DOIs, to
335+
each release tag. Please use the
336+
[appropriate release](https://github.com/codemeta/codemeta/releases) of the
337+
CodeMeta schema in order to refer to the appropriate context file, e.g.
220338

221339
```json
222340
"@context": "https://w3id.org/codemeta/3.1"
223341
```
224342

225-
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.
343+
## Referencing CodeMeta
226344

227-
## Testing An Instance file
345+
Release candidate versions may be referred to consistently using their
346+
[git tag](https://github.com/codemeta/codemeta/tags) for the raw version, e.g.
347+
<https://raw.githubusercontent.com/codemeta/codemeta/2.0-rc/codemeta.jsonld>.
348+
*Please do not refer to the raw GitHub URL for the master branch*, as this is
349+
/subject to change and will not guarantee a stable metadata file.
228350

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

0 commit comments

Comments
 (0)