Diagnostics#
For anyone maintaining research software. What each finding means and how to resolve it.
Every finding rs-metadata reports carries one of the codes below. Codes are a public interface: within a major version a code never changes meaning, so it is safe to filter on one, link to one, or key an editor integration off one.
Run rs-metadata explain <code> for the same information in a
terminal.
Severity#
Severity |
Meaning |
|---|---|
|
The metadata is wrong. Fails the build by default. |
|
The metadata works but should be improved. Non-fatal unless |
|
Context: something was noticed, or deliberately not checked. Never fatal. |
Severity is a property of the finding. Turning a severity into a build
failure is policy, controlled by --fail-on — the same report can
drive a strict institutional gate and a lenient local check.
Index#
Code |
Severity |
Summary |
|---|---|---|
|
A source carries values the anchor record does not |
|
|
Two metadata files disagree about the same concept |
|
|
A mapped field could not be meaningfully compared |
|
|
rs-metadata failed unexpectedly |
|
|
A value comes from a deprecated vocabulary entry |
|
|
The JSON-LD context is missing or does not declare CodeMeta |
|
|
A property has the wrong shape |
|
|
A property value is not valid |
|
|
A value is understood but not in the canonical form |
|
|
A value was copied from an example and never filled in |
|
|
A mandatory profile field is missing |
|
|
A property is not part of CodeMeta 3.1 |
|
|
A property outside the CodeMeta vocabulary is written unprefixed |
|
|
A field is present but could carry more information |
|
|
A recommended field is absent |
|
|
An optional metadata source was detected |
|
|
A metadata file does not satisfy its own format’s schema |
|
|
A required metadata file was not found |
|
|
A metadata file could not be parsed |
Profile#
The anchor record does not satisfy the LUMC profile.
profile.deprecated-value#
A value comes from a deprecated vocabulary entry — reported at warning at most.
The identifier is recognized but its issuing vocabulary has deprecated it in favor of a replacement.
How to resolve it. Replace it with the current identifier.
profile.invalid-context#
The JSON-LD context is missing or does not declare CodeMeta — reported at error at most.
Without the CodeMeta context, property names in the file have no globally defined meaning and consumers cannot interpret the record. The context is what turns a JSON file into linked data.
How to resolve it. Set “@context” to [“https://w3id.org/codemeta/3.1”, {“schema”: “https://schema.org/”}].
profile.invalid-type#
A property has the wrong shape — reported at error at most.
The value does not match the structure CodeMeta defines for this property, for example a bare string where a node object is required, or an object where a list of them is expected.
How to resolve it. Correct the value’s shape to match the profile schema.
profile.invalid-value#
A property value is not valid — reported at error at most.
The value has the right shape but cannot be correct: a malformed identifier, an ORCID or ROR whose checksum does not verify, or a date that is not a calendar date. Severity follows how certain the check can be — a value that cannot be right is an error, while one that is merely outside a preferred vocabulary is a warning.
How to resolve it. Replace the value with a well-formed one.
profile.non-canonical-value#
A value is understood but not in the canonical form — reported at warning at most.
The value is unambiguous, but CodeMeta and this profile both prescribe a different spelling of it. Non-canonical values still work with rs-metadata, which normalizes them, but they may not round-trip through other CodeMeta consumers.
How to resolve it. Rewrite the value in the canonical form shown in the message.
profile.placeholder-value#
A value was copied from an example and never filled in — reported at error at most.
The value is one of the placeholders that circulate in metadata templates and in the rs-metadata examples, such as the all-zero ORCID, a 10.0000/ DOI, or an example.com repository URL. Left in place it is worse than an empty field: it asserts a specific identity or identifier that does not exist, and registries will harvest it.
How to resolve it. Replace the placeholder with the real value for this software.
profile.required-field#
A mandatory profile field is missing — reported at error at most.
The LUMC profile requires this CodeMeta property in every research software record, so it is an error rather than a recommendation.
How to resolve it. Add the property to codemeta.json. See docs/using/profile.md for the accepted value shapes and worked examples.
profile.unknown-property#
A property is not part of CodeMeta 3.1 — reported at warning at most.
The property is not defined by the CodeMeta 3.1 context and is not an absolute IRI or a prefixed term. Most often this is a typo. The LUMC profile does not forbid extra properties, so this is a warning: unknown terms are simply ignored by consumers.
How to resolve it. Correct the spelling, or write the property as a prefixed term whose prefix is declared in @context if the extension is intentional.
profile.unprefixed-term#
A property outside the CodeMeta vocabulary is written unprefixed — reported at error at most.
CodeMeta 3.1 does not define this term, so written without a prefix it expands to nothing and JSON-LD processors drop it silently. The data looks present in the file but is invisible to every consumer.
How to resolve it. Write the property with an explicit prefix, and make sure the prefix is declared in @context.
Recommendations#
The record is valid, but could be more useful to registries and archives. Recommendations never fail a build by default.
recommendation.incomplete#
A field is present but could carry more information — reported at info at most.
The value is valid, but a richer form exists that downstream systems can use: an author without an ORCID, or an affiliation without a ROR, cannot be disambiguated automatically.
How to resolve it. Add the missing identifier or sub-field where you have it.
recommendation.missing#
A recommended field is absent — reported at warning at most.
The field is not mandatory under the LUMC profile, but several registries require it and its absence limits how discoverable the software is. Recommendations never fail CI by default.
How to resolve it. Add the field to codemeta.json where it applies.
Sources#
A metadata file could not be found, read, or validated against its own format’s specification.
source.detected#
An optional metadata source was detected — reported at info at most.
Informational. rs-metadata found an additional metadata file and included it in the consistency comparison.
source.invalid#
A metadata file does not satisfy its own format’s schema — reported at error at most.
The file parses, but violates the specification of the format it claims to be, so consumers of that format will reject it.
How to resolve it. Correct the file against its format specification.
source.missing#
A required metadata file was not found — reported at error at most.
This file is required alongside codemeta.json, because registries and archives read it directly and a record without it is not citable through them. Optional, auto-detected formats are never reported this way; their absence is not a finding.
How to resolve it. Create the file in the repository root.
source.unreadable#
A metadata file could not be parsed — reported at error at most.
The file exists but is not well-formed in its own syntax, so nothing in it can be validated or compared.
How to resolve it. Fix the syntax error reported in the message.
Consistency#
Two metadata files describe the same concept differently.
consistency.incomplete#
A source carries values the anchor record does not — reported at info at most.
Not a contradiction. Another metadata file records something codemeta.json omits, which is usually fine but occasionally reveals metadata that was never copied across.
How to resolve it. Consider adding the missing values to codemeta.json if they belong in the canonical record.
consistency.mismatch#
Two metadata files disagree about the same concept — reported at error at most.
Both files describe the same metadata concept but give values that are not equivalent after normalization. One of them is stale. Because codemeta.json is the anchor record, the discrepancy is reported against it.
How to resolve it. Update whichever file is out of date so both describe the same release.
consistency.uncomparable#
A mapped field could not be meaningfully compared — reported at info at most.
A mapping between the two formats exists, but this particular value cannot be compared: the source declares it dynamically, the mapping loses too much information, or one side is absent. Reported so the report is a complete account of what was and was not checked.
Internal#
rs-metadata itself failed. Always worth a bug report.
internal.error#
rs-metadata failed unexpectedly — reported at error at most.
An unhandled condition inside rs-metadata. The metadata being validated is not necessarily at fault.
How to resolve it. Please report this at https://github.com/LUMC-DCC/rs-metadata/issues with the file that triggered it.