promise version 2026.7 (channel stable)
An unknown annotation is reported as unknown and nothing else. Finding the real spelling means guessing, and guessing has no feedback except another "unknown".
n.pr:3:24: unknown meta annotation `name
u.pr:2:30: unknown meta annotation `untagged
Working out how to rename a serialized field in BASE took five wrong guesses — `name, `rename, `json, `serialize_as, `wire — before `key landed. Every one returned the same sentence with a different word in it. The annotation is not in promise guide either (that gap is #42, item 3), so there was nothing to read and nothing to search.
Contrast the message the same feature gives when the annotation is right and the parameter is wrong:
u.pr:2:30: unknown parameter 'untagged' in `serializable; allowed: tag
That one is excellent. It ends the search in a single compile: it names what is allowed. The annotation-level error should do what the parameter-level error already does.
Suggestion
Print the annotations that are valid in the position, and suggest near-misses:
n.pr:3:24: unknown meta annotation `name
valid on a field: `final, `key, `value, `embed
did you mean `key?
The near-miss suggestion is the cheaper half and would have caught `rename → `key only by the position list, not by edit distance — so the position list is the part that matters. Most of these guesses are not typos of the right answer, they are the name the annotation has in some other language.
One naming note
Whatever this ends up called, not `json. Serialization here is format-agnostic — the same encode/decode drives JSON, TOML, and anything else that implements Encoder, so a JSON-specific spelling would be wrong on the type that gets written as TOML tomorrow. `key is fine on those grounds. `name would be a reasonable alias if aliases are wanted at all, but that is the language's call, not a request here.
promise version 2026.7 (channel stable)An unknown annotation is reported as unknown and nothing else. Finding the real spelling means guessing, and guessing has no feedback except another "unknown".
Working out how to rename a serialized field in BASE took five wrong guesses —
`name,`rename,`json,`serialize_as,`wire— before`keylanded. Every one returned the same sentence with a different word in it. The annotation is not inpromise guideeither (that gap is #42, item 3), so there was nothing to read and nothing to search.Contrast the message the same feature gives when the annotation is right and the parameter is wrong:
That one is excellent. It ends the search in a single compile: it names what is allowed. The annotation-level error should do what the parameter-level error already does.
Suggestion
Print the annotations that are valid in the position, and suggest near-misses:
The near-miss suggestion is the cheaper half and would have caught
`rename→`keyonly by the position list, not by edit distance — so the position list is the part that matters. Most of these guesses are not typos of the right answer, they are the name the annotation has in some other language.One naming note
Whatever this ends up called, not
`json. Serialization here is format-agnostic — the sameencode/decodedrives JSON, TOML, and anything else that implementsEncoder, so a JSON-specific spelling would be wrong on the type that gets written as TOML tomorrow.`keyis fine on those grounds.`namewould be a reasonable alias if aliases are wanted at all, but that is the language's call, not a request here.