From c93fbb68ea78397dea1684395b33c7ac4d7e1cb6 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 9 Dec 2025 22:11:48 -0800 Subject: [PATCH 01/16] Add hugo style blockquotes and infoblock styling for paragraphs --- .../CodeMeta-Pyramids/static/css/codemeta.css | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/themes/CodeMeta-Pyramids/static/css/codemeta.css b/themes/CodeMeta-Pyramids/static/css/codemeta.css index b5d1f96..7ea6e1f 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,43 @@ code{ dl, li { font-size: 14px; } + +/*! + * 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,'); +} From 8e8f7e7d67bb9f88f99122f2b7461871b01cf34f Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 9 Dec 2025 22:12:43 -0800 Subject: [PATCH 02/16] Rearrange and rewrite parts of the userguide --- content/user-guide.md | 227 ++++++++++++---- static/img/jsonld-references-diagram.svg | 313 +++++++++++++++++++++++ 2 files changed, 487 insertions(+), 53 deletions(-) create mode 100644 static/img/jsonld-references-diagram.svg diff --git a/content/user-guide.md b/content/user-guide.md index e344a7d..5ec5d7c 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -3,54 +3,80 @@ 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. + +### 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*. Key-value pairs are known as *property-value pairs* in JSON-LD +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 +86,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 +97,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 +113,44 @@ 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 `@`. + +These references work similar to includes in a programming language. +{.tip} + +Keywords are instructions for the processor of the file to refer to +previously stored information. This means that the exact same information can +be included multiple times, and pulled from a consistent source. + +The source can be an external resource, as depicted in the diagram below: + +![Diagram of a JSON-LD reference pulling data in from an external data source](/img/jsonld-references-diagram.svg) -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 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`. 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 also provide similiar utility to a function in a programming +language; they prompt the processor to output the same data in another place +in the file. +{.tip} + +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" ``` -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 +169,12 @@ 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 +199,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 +212,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 +228,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 +249,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. + +Putting key-value or property-value pairs in a different place in the document +hierarchy can change the meaning of the document. -For example, the above code is not equivalent to: +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 +284,67 @@ 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)`. + +### 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. +([link to full example](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)): + +```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" +} +``` ## 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 , 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/)). +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 +[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 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 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://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. +## Referencing CodeMeta -## Testing An Instance 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. +. +*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. -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". diff --git a/static/img/jsonld-references-diagram.svg b/static/img/jsonld-references-diagram.svg new file mode 100644 index 0000000..e28f850 --- /dev/null +++ b/static/img/jsonld-references-diagram.svg @@ -0,0 +1,313 @@ + + + + + + + + + + + + + codemeta.json + External data (an IRI, URL, etc) + + + + + + + + + + @ + : + : + : + : + + + + + + + : + : + : + + + From d3b924fa82acf161e882fe7ca2038a2698b60d16 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Wed, 10 Dec 2025 09:42:25 -0800 Subject: [PATCH 03/16] Correction re properties from review Co-authored-by: Val Lorentz --- content/user-guide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index 5ec5d7c..d3ea04b 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -50,8 +50,7 @@ filenames are valid, they will be less recognisable and may be overlooked. 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*. Key-value pairs are known as *property-value pairs* in JSON-LD -linked-data. +objects*. Keys are also known as *properties* in linked data. #### Simple Values From 2b76caab149b697856cf8a1d57e18d331c9c06b7 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Wed, 10 Dec 2025 16:01:08 -0800 Subject: [PATCH 04/16] Second revision of userguide refresh --- content/user-guide.md | 43 +- static/img/jsonld-references-diagram.svg | 475 +++++++++++------- .../CodeMeta-Pyramids/static/css/codemeta.css | 4 + 3 files changed, 318 insertions(+), 204 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index d3ea04b..aa90819 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -115,34 +115,35 @@ objects. For example: #### Keywords JSON-LD has the concept of Keywords, which are properties prefaced with a `@`. +Keywords instruct the processor how to *expand* the document with linked data. -These references work similar to includes in a programming language. +Keywords can pull in other data; like programming language includes, work +like functions; repeating the same data in multiple places, or act like a +setting; changing the rules for the data. {.tip} -Keywords are instructions for the processor of the file to refer to -previously stored information. This means that the exact same information can -be included multiple times, and pulled from a consistent source. +Some refer to external resources (such as `@context`), some (like `@list` and +`@type`) add new constraints on the values for the property, while others +include a copy of previously recorded information (`@id`). -The source can be an external resource, as depicted in the diagram below: +The diagram below visualises how `@context` instructs the externally stored +definition for CodeMeta to be *embedded* to *expand* the `codemeta.json` +document: ![Diagram of a JSON-LD reference pulling data in from an external data source](/img/jsonld-references-diagram.svg) -The JSON-LD "@type" keyword associates a JSON value or object with a well +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`. 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. +associates the `author` object with `http://schema.org/Person`. The +`@type` for any property which specifies a node (JSON object) should be +provided. The [terms page](/terms/) indicates these node types. -Keywords also provide similiar utility to a function in a programming -language; they prompt the processor to output the same data in another place -in the file. -{.tip} - -The "author" JSON object illustrates the use of the JSON-LD keyword "@id", +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: +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" @@ -168,7 +169,6 @@ individual is the `maintainer` of the software being described, like this: } ``` - JSON-LD operations can later *expand* this reference and *embed* the full information at both locations. @@ -290,8 +290,7 @@ represented as the `"url"` of `rmarkdown`, instead of being the url of ### 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. -([link to full example](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)): +root of a code repository: ```json { @@ -311,6 +310,8 @@ root of a code repository. } ``` +([Link to full example](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)). + ## The context Every CodeMeta document must refer to the context file *codemeta.jsonld*, for diff --git a/static/img/jsonld-references-diagram.svg b/static/img/jsonld-references-diagram.svg index e28f850..7cb106b 100644 --- a/static/img/jsonld-references-diagram.svg +++ b/static/img/jsonld-references-diagram.svg @@ -3,8 +3,8 @@ + + + + transform="translate(-5.0079697,-116.69188)"> codemeta.json + style="stroke-width:0.197145" + x="13.296935" + y="123.56516">codemeta.json External data (an IRI, URL, etc) + style="stroke-width:0.197145" + x="102.64538" + y="133.04567">External schema + sodipodi:nodetypes="ccc" /> - - - - + width="27.848846" + height="3.2892344" + x="8.839468" + y="161.50162" /> - - @ - : - : - : + style="font-size:2.82222px;fill:#2c89a0;fill-opacity:1;stroke-width:0.197145" + x="39.39204" + y="129.32054"> "https://w3id.org/codemeta/3.1" : + style="font-size:2.82222px;fill:#5a2ca0;fill-opacity:1;stroke-width:0.197145" + x="37.717575" + y="-162.26239">: + width="27.848846" + height="3.2892344" + x="99.391243" + y="144.30531" /> + width="22.843817" + height="3.2892344" + x="130.73279" + y="144.30531" /> : + style="font-size:2.82222px;fill:#2c89a0;fill-opacity:1;stroke-width:0.197145" + x="123.03152" + y="-150.33772">: : + style="font-size:2.82222px;fill:#2c89a0;fill-opacity:1;stroke-width:0.197145" + x="128.26933" + y="146.97173">: : + style="font-size:2.82222px;fill:#2c89a0;fill-opacity:1;stroke-width:0.197145" + x="126.29059" + y="-139.79448">: + width="63.013103" + height="18.486748" + x="96.865753" + y="136.62347" /> + @context : + + + + + + + + : + : + : + + + + : + @context : + {} diff --git a/themes/CodeMeta-Pyramids/static/css/codemeta.css b/themes/CodeMeta-Pyramids/static/css/codemeta.css index 7ea6e1f..855fe3f 100644 --- a/themes/CodeMeta-Pyramids/static/css/codemeta.css +++ b/themes/CodeMeta-Pyramids/static/css/codemeta.css @@ -322,6 +322,10 @@ dl, li { font-size: 14px; } +p img { + margin: 25px 0px; +} + /*! * infobox paragraphs and blockquotes */ From efad54d3e0b8dc5721ec1332d45ac482af972f45 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Fri, 12 Dec 2025 10:42:03 -0800 Subject: [PATCH 05/16] Apply review contribution; better way to introduce keywords Co-authored-by: Val Lorentz --- content/user-guide.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index aa90819..2d9a684 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -115,16 +115,14 @@ objects. For example: #### Keywords JSON-LD has the concept of Keywords, which are properties prefaced with a `@`. -Keywords instruct the processor how to *expand* the document with linked data. +Keywords which give instructions to the processor instead of describing relations +between entities. -Keywords can pull in other data; like programming language includes, work -like functions; repeating the same data in multiple places, or act like a -setting; changing the rules for the data. -{.tip} +This includes: -Some refer to external resources (such as `@context`), some (like `@list` and -`@type`) add new constraints on the values for the property, while others -include a copy of previously recorded information (`@id`). +* defining shorthands (`@context`, `@vocab`), +* changing value semantics (`@list` and `@set`, `@value`, `@language`, ...), +* intrinsically describing objects (`@id` and `@type`) The diagram below visualises how `@context` instructs the externally stored definition for CodeMeta to be *embedded* to *expand* the `codemeta.json` From 1072ed0fa9fe1fa666ddf2aab3dff4a726b02659 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Fri, 12 Dec 2025 12:52:14 -0800 Subject: [PATCH 06/16] Proofread fix --- content/user-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/user-guide.md b/content/user-guide.md index 2d9a684..d5c9f65 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -115,7 +115,7 @@ objects. For example: #### Keywords JSON-LD has the concept of Keywords, which are properties prefaced with a `@`. -Keywords which give instructions to the processor instead of describing relations +Keywords give instructions to the processor instead of describing relations between entities. This includes: From 5c1128aee7bcce9da728bd5389f08270556ec084 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 13 Jan 2026 10:09:49 -0800 Subject: [PATCH 07/16] Retract the diagram, pending workshopped replacement --- content/user-guide.md | 6 - static/img/jsonld-references-diagram.svg | 422 ----------------------- 2 files changed, 428 deletions(-) delete mode 100644 static/img/jsonld-references-diagram.svg diff --git a/content/user-guide.md b/content/user-guide.md index d5c9f65..e479de2 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -124,12 +124,6 @@ This includes: * changing value semantics (`@list` and `@set`, `@value`, `@language`, ...), * intrinsically describing objects (`@id` and `@type`) -The diagram below visualises how `@context` instructs the externally stored -definition for CodeMeta to be *embedded* to *expand* the `codemeta.json` -document: - -![Diagram of a JSON-LD reference pulling data in from an external data source](/img/jsonld-references-diagram.svg) - 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 diff --git a/static/img/jsonld-references-diagram.svg b/static/img/jsonld-references-diagram.svg deleted file mode 100644 index 7cb106b..0000000 --- a/static/img/jsonld-references-diagram.svg +++ /dev/null @@ -1,422 +0,0 @@ - - - - - - - - - - - - - - - - codemeta.json - External schema - - - - "https://w3id.org/codemeta/3.1" - : - - - - - - - : - : - : - - @context : - - - - - - - - : - : - : - - - - : - @context : - {} - - From f50b7f90040930f935854f7c834a11d7ae0b6487 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Fri, 16 Jan 2026 14:55:21 -0800 Subject: [PATCH 08/16] Mention the use of prefix for use of additional schema.org terms --- content/user-guide.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index e479de2..6fc6d9e 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -315,9 +315,12 @@ 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 -[the developer guide](/developer-guide/)). +terms that are explicitly listed on the [terms](/terms/) page. Users wanting +to include additional terms may: + +* Use the `schema:` prefix to define them as terms (for +example `"schema:Person"`), 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. From 99567ecf3aca815ed18916f3ec195a1818d60a4a Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Fri, 16 Jan 2026 23:14:56 -0800 Subject: [PATCH 09/16] Use a real life example of schema: prefix use --- content/user-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index 6fc6d9e..714889c 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -318,8 +318,8 @@ 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: -* Use the `schema:` prefix to define them as terms (for -example `"schema:Person"`), or +* 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 From 8f38b3862b7001a18b9e71cc309339b31ae1d5c3 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Sat, 17 Jan 2026 12:51:01 -0800 Subject: [PATCH 10/16] Better describe how the terms page indicates types --- content/user-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/user-guide.md b/content/user-guide.md index 714889c..eeb12db 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -128,7 +128,8 @@ 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 [terms page](/terms/) indicates these node types. +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 From 25f7c1a5c62f823ff63d372a77b24d8ad9a46791 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 20 Jan 2026 12:35:52 -0800 Subject: [PATCH 11/16] Mention tools page in the userguide --- content/user-guide.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/user-guide.md b/content/user-guide.md index eeb12db..270160a 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -25,6 +25,9 @@ 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 From 7e5bae75fbd3e22ee231d26e2cffa744a838ee0b Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 20 Jan 2026 12:40:09 -0800 Subject: [PATCH 12/16] Remove stray char --- content/user-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/user-guide.md b/content/user-guide.md index 270160a..0740a5d 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -345,5 +345,5 @@ 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. +subject to change and will not guarantee a stable metadata file. From 25568e3b8daa24beefa9ed034b1bee7bda7f5a72 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 20 Jan 2026 13:25:31 -0800 Subject: [PATCH 13/16] Changes for Context and Referencing sections --- content/user-guide.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index 0740a5d..101acaf 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -310,7 +310,7 @@ root of a code repository: ## The context -Every CodeMeta document must refer to the context file *codemeta.jsonld*, for +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. @@ -318,7 +318,7 @@ 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 +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: @@ -329,11 +329,14 @@ as `"schema:releaseNotes"` [in this example](https://github.com/SciCodes/somef-c 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 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" @@ -341,9 +344,10 @@ CodeMeta schema in order to refer to the appropriate context file, e.g. ## Referencing CodeMeta -Release candidate versions may be referred to consistently using their -[git tag](https://github.com/codemeta/codemeta/tags) for the raw version, e.g. -. +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. . + *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} From 7633bc274bb53149657f89abcb49872f2cd494f1 Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 20 Jan 2026 17:25:36 -0800 Subject: [PATCH 14/16] Rearrange doc and add section describing people, roles, orgs etc. --- content/user-guide.md | 196 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 170 insertions(+), 26 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index 101acaf..24b0063 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -283,32 +283,7 @@ 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)`. -### 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/master/codemeta.json)). - -## The context +## 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 @@ -342,6 +317,175 @@ For example, use the following for the latest release: "@context": "https://w3id.org/codemeta/3.1" ``` +## 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-0220-0482", + "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-5231-3346", + "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` property to define the +participation of a `Person`. + +This is distinct from the `contributor` and `maintainer` properties. + +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/main/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/master/codemeta.json)). + ## Referencing CodeMeta All versions, including release candidates, may be referred to consistently From 9cf3fa04ce1d84d53a2902b42fae7a9f4f4bbc0b Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 20 Jan 2026 23:47:08 -0800 Subject: [PATCH 15/16] Apply suggestions from code review Co-authored-by: Val Lorentz --- content/user-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index 24b0063..6815f2d 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -353,7 +353,7 @@ the `author` object. For example: ```json "author": { - "@id": "http://orcid.org/0000-0003-0077-4738", + "id": "http://orcid.org/0000-0003-0077-4738", "@type": "Person", "email": "slaughter@nceas.ucsb.edu", "givenName": "Peter", @@ -367,7 +367,7 @@ array (`[`, `]`) of objects, as follows: ```json "author": [ { - "id": "https://orcid.org/0000-0002-0220-0482", + "id": "https://orcid.org/0000-0002-1825-0097", "type": "Person", "affiliation": { "type": "Organization", @@ -378,7 +378,7 @@ array (`[`, `]`) of objects, as follows: "givenName": "Bertrand" }, { - "id": "https://orcid.org/0000-0002-5231-3346", + "id": "https://orcid.org/0000-0002-2771-9344", "type": "Person", "affiliation": { "type": "Organization", @@ -431,7 +431,7 @@ providing this link. ``` -[Full example](https://github.com/oss-slu/Pi4Micronaut/blob/main/codemeta.json). +[Full example](https://github.com/oss-slu/Pi4Micronaut/blob/de4305bec9afe7f7c948e9cc97b9105fd55121f7/codemeta.json). ### Organizations @@ -484,7 +484,7 @@ root of a code repository: } ``` -([Link to full example](https://github.com/gem-pasteur/macsyfinder/blob/master/codemeta.json)). +([Link to full example](https://github.com/gem-pasteur/macsyfinder/blob/69c22b065065105e6c5ac8dcbff00a804a0a34fc/codemeta.json)). ## Referencing CodeMeta From f0d5bdaac26762225de724833cb5abe7741e934b Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Wed, 21 Jan 2026 11:27:17 -0800 Subject: [PATCH 16/16] Improve explanation of per feedback --- content/user-guide.md | 42 +++++++++++++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/content/user-guide.md b/content/user-guide.md index 6815f2d..e64ad48 100644 --- a/content/user-guide.md +++ b/content/user-guide.md @@ -399,10 +399,42 @@ refer to a consistent identity of an individual. ### Roles -The `Role` type property is used within the `author` property to define the -participation of a `Person`. +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. -This is distinct from the `contributor` and `maintainer` properties. +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 @@ -416,17 +448,13 @@ providing this link. "givenName": "Ruthvik", "type": "Person" }, - ... - { "roleName": "Tech Lead", "schema:author": "https://github.com/ruthvikm", "type": "Role" }, - ... - ] ```