Deprecation Reporting

Editor’s Draft,

This version:
https://wicg.github.io/deprecation-reporting/
Version History:
https://github.com/WICG/deprecation-reporting/commits/gh-pages
Editor:
(Google Inc.)
Participate:
File an issue (open issues)

Abstract

This document defines mechanism for reporting use of deprecated features to site owners through the use of the Reporting API.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

[INTRODUCTION GOES HERE]

1.1. Examples

Example, Inc. wants to keep track of when users are using Web APIs on its site which are going to be removed in upcoming browser versions. It can do this by delivering the following header to define a reporting endpoint, and direct deprecation reports to it:
Report-To: { "group": "default",
             "max_age": 10886400,
             "endpoints": [
               { "url": "https://example.com/reports", "priority": 1 },
               { "url": "https://backup.com/reports", "priority": 2 }
             ] }

2. Deprecation Reports

Deprecation reports indicate that a browser API or feature has been used which is expected to stop working in a future update to the browser.

Deprecation reports are a type of report.

Deprecation reports have the report type "deprecation".

Deprecation reports are visible to ReportingObservers.

[Exposed=(Window,Worker)]
interface DeprecationReportBody : ReportBody {
  [Default] object toJSON();
  readonly attribute DOMString id;
  readonly attribute Date? anticipatedRemoval;
  readonly attribute DOMString message;
  readonly attribute DOMString? sourceFile;
  readonly attribute unsigned long? lineNumber;
  readonly attribute unsigned long? columnNumber;
};

A deprecation report’s body, represented in JavaScript by DeprecationReportBody, contains the following fields:

Note: Deprecation reports are always delivered to the endpoint group named default; there is currently no way to override this. If you want to receive other kinds of reports, but not deprecation reports, make sure to use a different name for the endpoint group that you choose for those reports.

3. Sample Reports

    POST /reports HTTP/1.1
    Host: example.com
    ...
    Content-Type: application/reports+json

    [{
      "type": "deprecation",
      "age": 32,
      "url": "https://example.com/",
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
      "body": {
        "id": "websql",
        "anticipatedRemoval": "2020-01-01",
        "message": "WebSQL is deprecated and will be removed in Chrome 97 around January 2020",
        "sourceFile": "https://example.com/index.js",
        "lineNumber": 1234,
        "columnNumber": 42
      }
    }]
}

4. Security Considerations

For a discussion of security considerations surrounding out-of-band reporting in general, see Reporting API §security.

The remainder of this section discusses security considerations for deprecation reporting specifically.

5. Privacy Considerations

For a discussion of privacy considerations surrounding out-of-band reporting in general, see Reporting API §privacy.

The remainder of this section discusses privacy considerations for deprecation reporting specifically.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.es/ecma262/
[REPORTING-1]
Douglas Creager; et al. Reporting API. 25 September 2018. WD. URL: https://www.w3.org/TR/reporting-1/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

[Exposed=(Window,Worker)]
interface DeprecationReportBody : ReportBody {
  [Default] object toJSON();
  readonly attribute DOMString id;
  readonly attribute Date? anticipatedRemoval;
  readonly attribute DOMString message;
  readonly attribute DOMString? sourceFile;
  readonly attribute unsigned long? lineNumber;
  readonly attribute unsigned long? columnNumber;
};