schema: the software-only description states a narrower rule than §3.1.1 mandates #232

Spec section affected

schema/trace-claim.json (runtime.platform field description) vs §3.1.1 and docs/schema.md.

Problem

The schema's field description and the specification prose state different rules for what software-only marks, and the schema is the text a validator (and most integrators) actually read.

schema/trace-claim.json, on runtime.platform:

software-only marks development-mode records with no hardware backing; they must never be treated as attested evidence.

§3.1.1:

runtime.platform: "software-only" is the honest platform value in both cases […] It is the correct value for a dev-mode record, where nothing attested the execution, and for a record transcribed from another vendor's control plane, where the party asserting the evidence also wrote the log.

and, same section:

A record whose origin.kind is not self MUST carry runtime.platform: "software-only", and a verifier MUST reject it otherwise.

So the spec mandates software-only on every record assembled from someone else's evidence — a class that is not "development-mode records". A consumer that reads only the schema description gets a narrower rule than the one the spec normatively states, and has no reason to look further: the description reads as complete.

docs/schema.md follows §3.1.1 (two situations), so this is two documents against one, with the outlier being the machine-adjacent one.

Same shape as #172 (docs/trust-levels.md vs schema on slsa_level), which was resolved by aligning the texts.

Proposed change

Align the schema description with §3.1.1. For example:

software-only marks records with no hardware root of trust: a development-mode execution, or a record assembled from evidence produced outside the runtime (origin.kind other than self requires this value; see §3.1.1). Such records are not attested evidence.

Wording is the editors' call; the defect is only that the two texts currently state different rules.

Backward compatibility

• Non-breaking (new optional field, informative addition)
• Breaking (removes or changes required field, changes wire format, changes algorithm set)

Description text only; the enum and validation behaviour are unchanged.

Motivation

Surfaced while mapping a software-only producer (#231): this description is the line that decides how a conformant consumer weighs every record such a producer emits, so which text is authoritative matters more than usual for a docstring.

Related issues or PRs

#231, #172.

AI was used to revise grammar and translation, but initially I wrote it myself.

Thanks - Alex.