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 mdn/content#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?