Report type types coep

[hamishwillee]

This creates a PR to test the suggestion for structuring Reporting API report body types made in #27021 - what was suggested there did not quite survive attempted rollout.

For context,

• we currently a Report API with properties type, body, url.
• The .body can take an object that is derived from ReportBody that differs based on the type.
• The Report, ReportBody, and derived types such as InterventionReportBody were originally IDL objects, which means that previously we could document body types in the body interfaces, such as InterventionReportBody
• Now we have some body types that are dictionaries, some with no name at all. The plan is for ReportBody and possibly even Report to be dictionaries.
• Right now we agreed in Reporting API Report body - how do I document the COEP body report? #27021 that we can record the body type compat in Report. Note that eventually this will probably have to go in ReportingObserver. Yuck.

We have is a whole bunch of different string values for Report.type. We also have a whole bunch of possible report body properties, which vary or might potentially vary by type.

@caugner Generally we document all properties of the web API objects (not just the ones that have changed). Since these properties "live" in an object mapped to Report.body that's where I've added them, grouped by type. So it looks like this:

api.Report
  .type
  .body
      type_coep # The body type. Inside here go all the properties.
         type # Yes, the body itself also can have a type
         destination # non-standard
         disposition
         blockedURL
      type_csp-violation
         - blocked_url
         - columnNumber
         - .... [not yet done]
      type_all_the other_types
    ...
  .url

Note that I haven't yet added all the properties for the other types such as type_csp-violation - not worth it unless you agree this is the right approach.
Let me know.

Related docs work done in mdn/content#39880

[github-actions]

Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs).

[hamishwillee]

@caugner Thanks for your attention and taking this up in the BCD meeting.

The spec is now updated in w3c/reporting#284 so Report and ReportBody are dictionaries. Of course they will be in the IDL for all the current bodies etc until code can be changed, and hence exposed on the global object.

But what this means is that this has become a "real" problem affecting all the current report types.
Adding this to Report as I have done may not be the right thing.

If BCD is going to avoid dictionaries then the only option I see here is to add the information somehow to ReportingObserver.

The actual place the objects appear is in a callback method that you pass to the ReportingObserver constructor. This really doesn't have something you can hook to, so maybe the right place would be as a set of subfeatures of ReportingObserver with keys like reports_coep, reports_csp-...

EDIT PS, I think this does mean we need to deprecate to_json in the ReportBody now. Going forward all of these will disappear if BCD is consistent in how it handles dictionaries. Don't know how you will handle the between times though.

[hamishwillee]

@caugner And it just got even more messy in w3c/reporting#216 (comment) which seems to indicate that only report bodies which need to show up in ReportingObserver need a dictionary.

The implication, which I am checking, is that COOP and COEP report types only appear in reporting server endpoints - i.e. they are JSON objects posted to a server and not things you can get via ReportingObserver.

I have no idea what the "right thing" to do is now for COEP, COOP. Probably what we are proposing to do here, but you might argue that the information should go as a subfeature of the respective COOP / COEP headers - and I couldn't argue that.

But the discussion above is still value for the other reporting types.

[caugner]

I have no idea what the "right thing" to do is now for COEP, COOP.

It would be good to have another pair of eyes on this one, possibly @Elchi3 or @ddbeck.

[hamishwillee]

@caugner I think the way this is now is the correct way to do this. Naming convention might not be right, but I think the approach is. Can you review?

The body type is changing so that instead of getting an interface it will get a dictionary (already in spec, but not changed for old cases in the implementations). My thinking therefore is that we need to be able to indicate what body types are supported inside the body feature like this:

- api
  - Report
    - type
	- body
	  - type_coep_dict
	  - type_csp-violation_CSPViolationReportBody
	  - type_intervention_InterventionReportBody
	  - etc....
	- url

So coep is defined as an unamed object (i.e. a dict with no name). So here we indicate that as something like type_coep_dict.

Right now a csp-violation Report.body is a CSPViolationReportBody, so we indicate that as type_csp-violation_CSPViolationReportBody. If it becomes a dictionary in an implementation we'd deprecate this feature, and mark the version removed. Then we'd add type_csp-violation_dict to indicate this is now a dict.

We don't record the subfeatures unless they change for the particular type.

---

The only other way to do this is perhaps to add subfeatures to indicate the existing report types are dictionaries, and the versions in which that happens - such as

- api.ReportBody
  - is_a_dictionary

- api.CSPViolationReportBody
  - is_a_dictionary

This is good for the docs, but I don't see that as workable for BCD because you still need to find some way to report the coep dict - which as a dict you won't able to add a record for. YOu'll also have all these derived dicts you'll need to remove at some point.

[ddbeck]

This came up on today's BCD call. I took a look at the spec and the discussion for it. I'm sorry that they've done this to you, Hamish.

If these really are dictionaries, then there's no real support story to talk about. The purist move would be to sidestep a lot of this:

• For api.Report and any other report dictionaries in api, set deprecated to true (taking the removal from the spec as a de facto deprecation). If a browser does not expose the interface, then set "version_added": false or "version_removed" accordingly.

• Show that developers can get reports of the various dictionary types via ReportingObserver. That is, make these features:

  api.ReportingObserver.ReportingObserver.options_parameter.types_property.csp-violation
  api.ReportingObserver.ReportingObserver.options_parameter.types_property.deprecation
  api.ReportingObserver.ReportingObserver.options_parameter.types_property.integrity-violation
  api.ReportingObserver.ReportingObserver.options_parameter.types_property.intervention
  

On MDN, I would suggest documenting the report body dictionaries as dictionaries (i.e., don't mention the interfaces). I would use the api.ReportingObserver.ReportingObserver.options_parameter.types_property.* keys for the compat tables on those pages, to show that those dictionaries exist.