Design decisions

Design decisions#

Why the validator behaves the way it does.

Value types are derived and enforced#

For every property, CodeMeta declares what kind of value it can hold. However, JSON-LD does not reject a wrong type, it silently coerces: a bare "Apache-2.0" where a CreativeWork or URL is expected becomes a relative IRI, which resolves into something meaningless or is dropped.

So, the rule is:

A property with no Text type branch must be a node or an absolute URL. A bare string there is unresolvable and leads to an error.

The types themselves are automatically derived from CodeMeta’s own property table, fetched by scripts/vendor_reference_data.py and stored as data/codemeta-3.1-types.json.

Both CodeMeta and schema.org are used, in that order of authority. CodeMeta narrows schema.org for its own profile. For example, schema.org allows maintainer to be a Person or an Organization, whole CodeMeta only allows Person. However, CodeMeta misses some properties required by the LUMC profile, which is why this profile writes schema:featureList with a prefix. Those come from schema.org.

The two vocabularies are matched by IRI, not by name. Some CodeMeta terms expand to CodeMeta’s own IRIs rather than to schema.org ones. The vocabularies have different properties that happen to share a name, so merging their ranges would violate the CodeMeta’s constraints.

The generated schema defines no classes at all. Its four $defs are structural: non-empty text, an absolute IRI, an ISO 8601 date, and a generic node. The class check happens against the vocabulary. A contract test asserts that no $defs entry ever names a vocabulary class.

Two things stay hand-written, because no vocabulary states them:

  • Cardinality. Whether a property takes one value or several is a profile decision. E.g., software has one name and can have several authors.

  • Remediation text, optionally. Each field is described with its vocabulary’s own definition, which suits a tooltip but often does not say how to fix a file.

Crosswalks cover full CodeMeta#

The profile includes 25 CodeMeta properties. CodeMeta has many more, and its published crosswalks map many of them. Whether the profile requires a field and whether two files disagree about it are separate questions. A codemeta.json and a DESCRIPTION that list different optional dependencies are still noted. So mappings cover every record-level property an upstream crosswalk names, and a contract test enforces it against the vocabulary’s own notion of which properties belong to the record. However, the concepts beyond the profile are kept as informational. The profile has no opinion about dateModified, so rs-metadata may show a difference but must never fail a build over one.

Value absence#

The absense is not treated as disagreement. A dependency listed in pyproject.toml but not in codemeta.json is incompleteness, not a contradiction, and is not reported as a conflict. Only genuinely incompatible values are. Equivalent constraints are compared semantically, so >=1.24 and >=1.24.0 do not disagree.

Missing recommended fields arrive as one aggregated warning rather than one warning each.

Best-effort comparison#

The dedicated strategies each know something: that versions are ordered, that SPDX identifiers have synonyms, that two spellings may be one person. That knowledge is what makes them strict enough to throw an error over. The properties outside the profile assume no such knowledge. They irreducible values are declines for comparison and reported as seen and not judged.

Subtypes#

A subtype is an acceptable @type. A PropertyValue slot accepts a LocationFeatureSpecification, because schema.org says the latter is a kind of the former. In schema.org, a subclass is substitutable for its parent, and CodeMeta inherits that.

The hierarchy is read from schema.org rather than enumerated, so the accepted set stays correct as schema.org adds classes.

Identifier ambiguity#

An identifier may live in @id or in identifier. Both are correct JSON-LD, so both are accepted. @id is the node’s IRI, and identifier is a property whose value may be a URL or a PropertyValue. A comparison against a companion file reads @id first and falls back to identifier, so the same ORCID written two ways across two files is not reported as a disagreement.

Formats#

Format rules are the one thing not derived from upstream, because nothing publishes them in machine-readable form. schema.org defines Date as “a date value in ISO 8601 date format”, in prose only. We implement the standard each datatype name denotes.