Scoping the extensions slot (follow-up to #286)

[CaseyRo]

Is your feature request related to a problem? Please describe.

In #286 @peteski22 indicated that a relaxation of additionalProperties: false is "probably, but not yet", with a preference for an explicit extensions slot over x- prefixed keys — and invited scoping the shape in advance. This issue is that scoping thread.

Today, independent implementations that carry extra fields must strip them before any wire transmission (Stolperstein does this via a strict-mode serializer; our extension registry is here). That works, but it means any two installs of the same implementation also lose their shared fields the moment a KU crosses the wire — the stripping is lossier than the portability concern requires.

Describe the solution you'd like

A single optional top-level slot:

"extensions": {
  "type": "object",
  "description": "Implementation-specific fields. Not portable across implementations; consumers MUST ignore unknown keys and MUST NOT rely on their presence.",
  "additionalProperties": true
}

With four rules in the docs rather than the schema:

1. Namespacing recommended: keys prefixed with an implementation slug (stolperstein:severity) so two implementations can't collide silently.
2. Consumers MUST ignore unknown keys; validators MUST NOT fail on anything inside extensions.
3. No protocol semantics: nothing inside extensions may change how a conforming consumer ranks, trusts, flags, or graduates a KU. If it needs to, it's a schema proposal, not an extension.
4. Top-level additionalProperties stays false — the slot is the only escape hatch, which keeps it greppable across implementations (the argument from Schema extensions from an independent implementation (Stolperstein) #286).

Open questions worth settling here:

• Does extensions content participate in any future signing/hashing of KUs, or is it explicitly outside the signed envelope? (We'd argue outside — it lets receivers strip it without invalidating signatures.)
• Size guidance — a SHOULD-level soft cap so the slot doesn't become a blob store?
• Do confirmations/flags apply to the KU regardless of extensions drift between versions? (We'd argue yes — extensions are not part of unit identity.)

Describe alternatives you've considered

x- prefixed top-level keys (rejected in #286 — harder to grep and constrain), and the status quo (strip everything — works but is lossier than needed between same-implementation installs).

Self-Checklist

• I have read the Contributing Guidelines.
• I have searched the existing issues and found no duplicate.
• I have provided a clear and concise description of the problem.
• I have provided a clear and concise description of the proposed solution.

[peteski22]

Hi @CaseyRo, thanks for putting this together. I've moved it to the RFC discussions as I think this is worthy of being tracked here as it's shaped.

This captures the #286 direction well; a named extensions slot rather than x-, top-level additionalProperties: false kept as the single greppable boundary, and the constraints living in the docs.

Rule 3 is the key one: anything that moves how a consumer ranks/trusts/flags/graduates a KU is a schema proposal, not an extension... that's exactly the line we want, and it keeps the observed-over-declared posture intact.

Reading this as scoping the shape, not a decision to enable it yet; the "have we earned the relaxation" call stays separate. I'll take the open questions (signing envelope, size cap, unit identity) inline.

Does extensions content participate in any future signing/hashing of KUs, or is it explicitly outside the signed envelope? (We'd argue outside — it lets receivers strip it without invalidating signatures.)

I agree that it should come outside as the KU 'core' is what we want to be able to assert about within and across cq servers.

Size guidance — a SHOULD-level soft cap so the slot doesn't become a blob store?

I'd say yes to this also, potentially there could be a 'total' soft cap, and a per extension field soft cap. But I agree it would be good to dissuade folks from trying to store things in here that don't really belong.

Do confirmations/flags apply to the KU regardless of extensions drift between versions? (We'd argue yes — extensions are not part of unit identity.)

I'm in agreement with you here, yes they should ignore the extensions and be focused on the core of the KU (summary, action, insight etc.)

---

How do you want to take this forward, is it something you'd like to contribute yourself to the repo?