Add a reference to the governing terms, distinct from `license_ref`

[jwrosewell]

license_ref (5.2.3) references the licence a content access protocol issued, given as "a JWT jti claim, a CoMP package ID, or any opaque identifier that both parties can resolve", and the one fixture that sets it uses a JWT. It is proof of a grant, not the terms the grant rests on. The protocols it connects to (1.4) each keep their terms in a separate artifact and pass only a grant identifier.

The standard has no field for the terms a piece of content is offered under, and 8.9 lists "content licence declarations" as deferred. So a telemetry record names the grant but never the terms it was produced under. That blocks enforcement, since usage cannot be measured against what was permitted, and where the terms govern by access with no token issued, license_ref is empty and the record points at nothing.

Add an optional terms_ref on the event or session, naming the governing terms, distinct from license_ref. Like license_ref, it MAY be a public URL or an opaque identifier the parties resolve privately, and it should not require a public or well-known location, since confidential per-party terms cannot be exposed there. A Terms Document Locator (TDL, jwrosewell/data-labels) is one example of such a terms document reference, in either form.

terms_ref is the basis, license_ref is the proof. Carrying both lets a record say which terms governed an event and which grant, if any, authorised it.

[erik-sv]

+1 on terms_ref as distinct from license_ref. The gap is real: license_ref is proof of a grant, and in the access-governed case where no token is issued it is empty, so the record points at nothing while the terms that actually govern go unstated. An optional terms_ref, a URI or an opaque identifier resolved privately and not requiring a well-known location, fixes that, and "the basis versus the proof" is a clean way to put it.

One addition from the provenance side, since it bears on making terms durable rather than only referenced. A content-borne identifier can carry the terms_ref in-band, bound to the content itself, so the terms reference travels with the content through copy and syndication and survives the operations that detach a sidecar artifact. The same in-band channel that carries a verifiable content_id can carry the terms_ref alongside it, so identity and the governing-terms reference move together with the asset rather than being re-resolved from context that may be gone.

This stays within the test in #4 that an event be readable from the public schemas: terms_ref remains a plain field, and in-band carriage is an implementation option for emitters that want the reference to persist with the content, not a required resolution layer or vendor dependency. So: support the field, and flag that a content-derived provenance scheme is one way to make the terms reference persist with the content, not only accompany the event.

[jalexspringer]

Unattributed consultation feedback for the record - input for triage, not a maintainer decision or resolution.

Direct publisher feedback received outside GitHub during the comment window supports the need for a clearer pathway from telemetry to attribution, licensing, and compensation, while preserving flexibility across licensing models.

That lines up with the distinction proposed here. license_ref identifies the grant or issued authorisation. A separate terms_ref would let the event point at the governing terms or reporting obligations that explain how the telemetry should be interpreted, including cases where the deal is enterprise, catalogue-based, or relationship-based rather than per-event.

That would help connect telemetry to licensing without baking a pricing model into the core event vocabulary.

[jalexspringer]

Disposition: accepted narrowly for core v1. terms_ref will be an opaque optional pointer, distinct from license_ref. Core carries the reference but does not interpret, resolve or validate the terms, and does not name TDL or any other scheme normatively. Its placement is being settled together with a session-level container for typed identifiers, so this issue stays open until that change merges into v1-draft.

[jwrosewell]

I have read the new contributor guidance and I take the point about proposals starting with the person who needs the thing rather than with generated specification text.

This sits between the two on purpose. The field is accepted but not yet written anywhere, v1 freezes on 21 August, and this is a technical specification where being vague would waste more of your time than mine. So the following is precise about what has to be true and is not offered as specification language. Take the meaning and write it whichever way fits the document.

To be clear about the ask, we are not proposing that core name any scheme, and we accept that core should not interpret, resolve or validate the terms. All of this is about the pointer rather than the document it points at.

Four things have to hold or the field records nothing.

1. The reference has to survive transmission. Where an emitter holds a terms reference for the content it is reporting on, the event should carry it, and anything that relays, aggregates, transforms or re-emits an event should pass the value through untouched. Replacing one reference with another is a matter for the terms themselves, but dropping one is not, and it is worth keeping those apart so that a party who strips the field cannot call it a replacement. This is the property the field lives or dies on, because terms_ref is needed precisely where license_ref is empty, and there the reference is the only record of the basis on which access happened. It is the same durability point @erik-sv made from the provenance side, reached from the carriage side instead.

2. The reference has to keep meaning the same thing. One reference should denote one set of terms for all time and never be reused for a different set. Otherwise the recorded value does not tell you what governed the event, because the terms behind it can be changed afterwards and nobody can tell which version applied. Where terms change, a new reference is created and later events carry it, which gives a timeline rather than a moving target. That is a property of the identifier, so core can require it without resolving anything.

3. The terms have to stay reachable. Whoever creates a reference needs to keep it reachable by the counterparty for as long as the record is kept. We accept this is likely a governing-terms duty rather than a core one, given core has to work without an external resolver, and we would rather say so than have you say it. It still needs to land somewhere, because a pointer nobody can follow is the same as no pointer.

4. A missing reference has to mean nothing. A reader should draw no inference from an absent terms_ref. Without that, leaving the field out starts to imply that no terms apply, which turns an optional field into a way of asserting the opposite of what it says.

The value should be treated as opaque and carried byte for byte, with no normalising, canonicalising or truncating, since that is the other way a pointer quietly stops working.

On placement, if the reference ends up in the session-level container of typed identifiers, these carriage properties need to attach at that level too, or the container becomes the place the value gets dropped.

@jalexspringer Given the freeze, if you would like the specific text and conformance fixtures written for this, say so and I will do it for your review. I understand alignment is important, so I will not open a PR against the specification until you ask. Otherwise I am glad to answer questions or supply concrete cases.

[jalexspringer]

Implemented in PR #45. terms_ref is an optional event-level field (new 5.2.4): a public URL or an opaque identifier both parties can resolve; private resolution conforms, since per-relationship terms are often confidential. license_ref records which grant applied; terms_ref records which terms govern the event's consequences and the emitter's reporting obligations; either appears without the other. Core carries the reference and does not resolve, validate or interpret it, and the terms it points at do not redefine core event semantics — they select events and coverage (new 5.7.6).

Placement: event-level only. A session-level default was considered and deferred — sessions legitimately span content under different terms, and the session container that landed alongside (5.1.3) holds typed access-context identifiers, not a terms slot. Fixture: tests/valid/event-standalone-terms-ref.json. Open until the PR merges into v1-draft.

[jwrosewell]

5.2.4 in #45 delivers the field this issue asked for, with the basis and proof distinction stated, the case where an access has terms but no grant written in, and a standalone fixture. Thank you.

Half of my comment of 12 August is now in the text, since core does not resolve, validate or interpret the reference. The carriage half is not yet stated, and it amounts to three sentences.

1. The value is carried byte for byte wherever a document is stored, forwarded or transformed, and is never removed or rewritten.
2. A terms_ref value denotes the same terms for all time. Terms that change are a new value, so a reader of an old event can still find the terms that governed it.
3. The absence of terms_ref carries no meaning. That is the same shape as the coverage rule in 5.7.6, where the absence of an event is not evidence, and it matters for the same reason, because otherwise silence acquires a meaning nobody declared.

With those stated I am happy for this issue to close. I can propose wording against the #45 text if useful, and the formal version is already in my comment of 12 August above.

[jalexspringer]

Adopted, in #45 (8b7083c). §5.2.4 now states the three rules: the reference is carried byte for byte and MUST NOT be removed or rewritten; a value denotes the same terms for all time, with changed terms taking a new value; and absence carries no meaning, stated in the same shape as the 5.7.6 coverage rule. Closing when #45 merges.

[jalexspringer]

Merged in #45: terms_ref (5.2.4) with the carriage rules stated.