Skip to content

Commit 1e65e0e

Browse files
moraneggmoranegg
authored
Merge pull request #35 from progval/expand-user-guide
Expand the user guide.
2 parents ed5b6be + a294461 commit 1e65e0e

File tree

1 file changed

+149
-9
lines changed

1 file changed

+149
-9
lines changed

‎content/user-guide.md‎

Lines changed: 149 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,34 +15,62 @@ Here is an example of a basic `codemeta.json` that you can put at the root of a
1515
```json
1616
{
1717
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
18-
"name": "Generate CodeMeta Metadata for R Packages",
18+
"@type": "SoftwareSourceCode",
19+
"name": "CodemetaR",
1920
"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.",
21+
"license": "https://spdx.org/licenses/GPL-3.0",
2022
"identifier": "http://dx.doi.org/10.5281/zenodo.XXXX"
2123
}
2224
```
2325

26+
### Basics
2427

2528
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:
2629

2730
```
2831
"name" : "R Interface to the DataONE REST API"
2932
```
3033

31-
A JSON array is surrounded by the characters `[` and `]`, and can contain multiple values:
34+
There must be a comma between of these key-value pairs, and no comma at the end before the closing bracket (`}`).
35+
36+
### Arrays
37+
38+
A JSON array is surrounded by the characters `[` and `]`, and can contain multiple values separated by commas:
3239

3340
```
3441
"keywords": [ "data sharing", "data repository", "DataONE" ]
3542
```
3643

44+
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:
45+
46+
```
47+
"keywords": [
48+
"data sharing",
49+
"data repository",
50+
"DataONE"
51+
]
52+
```
53+
54+
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:
55+
56+
```
57+
"license": [
58+
"https://spdx.org/licenses/GPL-3.0",
59+
"https://spdx.org/licenses/BSD-3-Clause"
60+
]
61+
```
62+
63+
### Objects
64+
3765
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:
3866

3967
```
4068
"author": {
41-
"@id":"http://orcid.org/0000-0003-0077-4738",
42-
"@type":"Person",
43-
"email":"[email protected]",
44-
"givenName":"Peter",
45-
"familyName: "Slaughter"
69+
"@id": "http://orcid.org/0000-0003-0077-4738",
70+
"@type": "Person",
71+
"email": "[email protected]",
72+
"givenName": "Peter",
73+
"familyName": "Slaughter"
4674
}
4775
```
4876

@@ -57,9 +85,121 @@ The "author" JSON object illustrates the use of the JSON-LD keyword "@id", which
5785
"maintainer": "http://orcid.org/0000-0003-0077-4738"
5886
```
5987

60-
(Note: this should be added at the top level of the document, indicating that this individual is the `maintainer` of the software being described.) JSON-LD operations can later *expand* this reference and *embed* the full information at both locations.
88+
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:
89+
90+
```json
91+
{
92+
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
93+
"@type": "SoftwareSourceCode",
94+
"name": "CodemetaR",
95+
96+
"author": {
97+
"@id": "http://orcid.org/0000-0003-0077-4738",
98+
"@type": "Person",
99+
"email": "[email protected]",
100+
"givenName": "Peter",
101+
"familyName": "Slaughter"
102+
},
103+
"maintainer": "http://orcid.org/0000-0003-0077-4738"
104+
}
105+
```
106+
107+
JSON-LD operations can later *expand* this reference and *embed* the full information at both locations. This means the example above is equivalent to:
108+
109+
```json
110+
{
111+
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
112+
"@type": "SoftwareSourceCode",
113+
"name": "CodemetaR",
114+
115+
"author": {
116+
"@id": "http://orcid.org/0000-0003-0077-4738",
117+
"@type": "Person",
118+
"email": "[email protected]",
119+
"givenName": "Peter",
120+
"familyName": "Slaughter"
121+
},
122+
"maintainer": {
123+
"@id": "http://orcid.org/0000-0003-0077-4738",
124+
"@type": "Person",
125+
"email": "[email protected]",
126+
"givenName": "Peter",
127+
"familyName": "Slaughter"
128+
}
129+
}
130+
```
131+
61132

133+
### Nesting objects
134+
135+
We saw before a simple (root) SoftwareSourceCode object:
136+
137+
```json
138+
{
139+
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
140+
"@type": "SoftwareSourceCode",
141+
"name": "CodemetaR"
142+
}
143+
```
144+
145+
and this root object can refer to other objects, for example recommend a SoftwareApplication:
146+
147+
```json
148+
{
149+
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
150+
"@type": "SoftwareSourceCode",
151+
"name": "CodemetaR",
152+
153+
"softwareSuggestions": {
154+
"@type": "SoftwareApplication",
155+
"name": "rmarkdown"
156+
}
157+
}
158+
```
159+
160+
And you may in turn want to add attributes to this application:
161+
162+
```json
163+
{
164+
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
165+
"@type": "SoftwareSourceCode",
166+
"name": "CodemetaR",
167+
168+
"softwareSuggestions": {
169+
"@type": "SoftwareApplication",
170+
"name": "rmarkdown",
171+
"provider": {
172+
"@type": "Organization",
173+
"name": "Central R Archive Network (CRAN)",
174+
"url": "https://cran.r-project.org"
175+
}
176+
}
177+
}
178+
```
179+
180+
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 softwareSuggestion of CodemetaR.
181+
182+
For example, the above code is not equivalent to:
183+
184+
```json
185+
{
186+
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
187+
"@type": "SoftwareSourceCode",
188+
"name": "CodemetaR",
189+
190+
"softwareSuggestions": {
191+
"@type": "SoftwareApplication",
192+
"name": "rmarkdown",
193+
"provider": {
194+
"@type": "Organization",
195+
"name": "Central R Archive Network (CRAN)"
196+
},
197+
"url": "https://cran.r-project.org"
198+
}
199+
}
200+
```
62201

202+
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)`.
63203

64204
## The context
65205

@@ -82,4 +222,4 @@ Release candidate versions may be referred to consistently using their git tag f
82222

83223
## Testing An Instance file
84224

85-
[ TBD ]
225+
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)