Reporting API Report body - how do I document the COEP body report?

[hamishwillee]

What type of issue is this?

Other

What information was incorrect, unhelpful, or incomplete?

The reporting API currently defines a Report instance that has a Report.body property that derives from ReportBody. For example CSPViolationReportBody. This all works rather nicely w.r.t. docs and BCD because the objects are all in IDL and so have a well understood name, derivation and their own API existence.

Unfortunately this is about to change. I'm documenting the body object for the report for COEP and COOP violations in https://github.com/mdn/content/pull/39880. For this case the specification does not define any IDL for the body object or state that it is derived from ReportBody. In fact they are planning on changing the spec for all of the body objects such that Report is a dictionary and ReportBody is an abstract dictionary.

In docs what I have done is define my own dictionary COEPViolationReportBody for COEP violation bodies. BCD doesn't document dictionaries, so what is the right way to record support for this?

I THINK that right now Report is an object so what we probably should do is

• add a subfeature under Report.type indicating each of the supported types (and we probably should do that anyway).
• under that add a subfeature indicating the properties allowed in each type.

1. Sounds complicated
2. Report will become a dictionary - what do we do then?
3. Right now we have some things that are derived from ReportBody, and some that aren't - how do we manage that?

What browsers does this problem apply to, if applicable?

No response

What did you expect to see?

NA

Did you test this? If so, how?

NA

Can you link to any release notes, bugs, pull requests, or MDN pages related to this?

NA

Do you have anything more you want to share?

https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API

MDN URL

No response

MDN metadata

No response

[caugner]

This sounds somewhat similar to input element types, where we have html.elements.input.type_X, although there we document all attributes directly under html.elements.input.

I think the following structure is fine:

• api.Report
• api.Report.deprecation_type
• api.Report.deprecation_type.id
• api.Report.deprecation_type.anticipatedRemoval
• … (other properties)
• api.Report.csp-violation_type
• … (all properties)
• api.Report.intervention_type
• … (all properties)

@hamishwillee Is this what you had in mind?

[hamishwillee]

Thanks @caugner . Yes, that is exactly what I was thinking, but probably initially only for the coep and coop violation types.

But if/when Report becomes a dictionary then we'll have to rethink, because BCD doesn't include dictionaries. At that point it is hard - there is nothing to hook this all to.

[hamishwillee]

Closing. This didn't "quite" work in that I thought the types should live under the body, and all properties should be documented, not just the ones that are incompatible.

Discussion moved to #27047

[caugner]

Reopening, as issues are a better place to discuss.

[hamishwillee]

Thanks @caugner - Do I need to copy the gist of the discussion across?

[hamishwillee]

1. The COEP and COOP reports are only intended to be sent as reports to server endpoints, so IMO their BCD entries should go as subfeatures of their respective HTTP headers.
   • Possibly as subfeature of the report-to directive?
2. Other reports are intended to be both send to server endpoints and reported by the Reporting API. My thinking is that since BCD doesn't love dictionaries, these should be subfeatures of the ReportingObserver (or possibly its constructor, since that is where the callback is defined).
   • You might also have them in the HTTP headers, but I don't think you'd just have them in the headers.

I was thinking for "2" maybe a key reports_<type>, with subfeature for each fields of those.

@caugner Did the BCD meeting have any thoughts on this?

[caugner]

Related spec PRs:

• https://github.com/w3c/reporting/pull/258
• https://github.com/w3c/reporting/pull/284

[hamishwillee]

@caugner I'm hoping to get back to this at some point. W.r.t. https://github.com/mdn/browser-compat-data/issues/27021#issuecomment-2998926966 do you have any thoughts on the structure? SHould I just PR something and we can argue it?