Automated Discovery Of Self-Published Reports (reports.json)
draft-dkg-reports-json-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Authors | Daniel Kahn Gillmor , Marissa Kumar Gerchick | ||
| Last updated | 2026-11-20 | ||
| Replaces | draft-dkg-audits-json | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources |
GitHub Repository
|
||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-dkg-reports-json-00
intarea D. K. Gillmor
Internet-Draft M. K. Gerchick
Intended status: Informational ACLU
Expires: 24 May 2027 20 November 2026
Automated Discovery Of Self-Published Reports (reports.json)
draft-dkg-reports-json-00
Abstract
This document describes a mechanism that an organization can use to
enable automatic discovery of documents associated with regulatory
compliance. It is motivated by regulations that require, for
example, publicly accessible reports of audits of automated decision-
making processes in hiring, or reports on sustainable business
practices.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://dkg.github.io/reports.json/. Status information for this
document may be found at https://datatracker.ietf.org/doc/draft-dkg-
reports-json/.
Source for this draft and an issue tracker can be found at
https://github.com/dkg/reports.json/.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 24 May 2027.
Gillmor & Gerchick Expires 24 May 2027 [Page 1]
Internet-Draft reports.json November 2026
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.4. Non-Goals . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Locating The reports.json Summary . . . . . . . . . . . . . . 4
3. reports.json Structure . . . . . . . . . . . . . . . . . . . 4
3.1. reports Content . . . . . . . . . . . . . . . . . . . . . 5
3.2. operations Content . . . . . . . . . . . . . . . . . . . 5
3.2.1. Regulation objects . . . . . . . . . . . . . . . . . 6
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.1. Normative References . . . . . . . . . . . . . . . . . . 6
5.2. Informative References . . . . . . . . . . . . . . . . . 7
Appendix A. Test Vectors . . . . . . . . . . . . . . . . . . . . 8
A.1. Example reports.json . . . . . . . . . . . . . . . . . . 8
Appendix B. JSON Schema For reports.json . . . . . . . . . . . . 9
Appendix C. Examples of Regulatory Regimes . . . . . . . . . . . 11
C.1. Example Regulatory Text . . . . . . . . . . . . . . . . . 11
Appendix D. Third-party Hosting . . . . . . . . . . . . . . . . 12
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12
Document History . . . . . . . . . . . . . . . . . . . . . . . . 12
Changes between audits.json-01 and reports.json-00 . . . . . . 12
Changes between audits.json-00 and audits.json-01 . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
Gillmor & Gerchick Expires 24 May 2027 [Page 2]
Internet-Draft reports.json November 2026
1. Introduction
An increasing number of regulatory regimes require organizations
involved in certain business practices to provide a degree of
transparency in their business operations by posting reports in an
accessible location. For example, New York City's 2021 Local Law 144
([NYC-LL144]) established auditing requirements for employers who use
automated decision-making tools in the employment process, but it has
proved challenging to even find these audit reports effectively (see
[Auditing-the-Audits]).
For a business that has a website, the natural place to provide
access to the audit report is on that website. This document
describes a standard mechanism that can be used to point to any
report posted associated with regulatory compliance.
The mechanism is a reports.json summary document, found at a well-
known URL, which allows the hosting domain to refer to specific
business operations, relevant regulatory regimes, and their
associated reports.
Adoption of this mechanism should make it easier for businesses to
comply with these requirements, while also making it easier for
researchers, analysts, and regulators to assess compliance and
evaluate the overall effectiveness of the regulations.
1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
1.2. Terminology
* A "report" is a document produced by an organization or an
independent entity commissioned by the organization to describe --
according to some kind of regulatory compliance -- a part of the
organization's business operations.
1.3. Goals
* Provide a standardized way for an organization to publicize
reports associated with given regulatory requirements.
* Provide a standardized way for a reviewer of reports associated
with a regulatory requirement to find those reports.
Gillmor & Gerchick Expires 24 May 2027 [Page 3]
Internet-Draft reports.json November 2026
1.4. Non-Goals
Discovering a report is merely the first step in a process of having
an effective regulatory regime based on these self-hosted reports.
This specification is focused on satisfying this necessary but
insufficient stage of larger work.
* This specification makes no attempt to describe the syntax or
semantics of any particular report. The underlying assumption is
that the reports for different regulations or compliance measures
will have different requirements for content, structure, syntax,
and so on.
* This specification also does not associate a real-world
organization with a particular domain name. If a researcher wants
to find the reports associated with Example Corp, they need to
associate Example Corp with the example.com domain name
independently in order to use this specification. Likewise, any
regulation making use of this mechanism needs to explicitly
describe the link between the regulated entity and the domain name
or domain names on which it is expected to publish this summary.
* This specification does not describe a way for a casual visitor to
a given website to find these reports. A regulation that requires
easy public accessibility of a report may need to offer additional
user interface or user experience guidance in addition to
requiring the use of this mechanism.
2. Locating The reports.json Summary
This specification uses the .well-known URL space defined by
[RFC8615].
A given domain hosts the reports.json summary in /.well-known/
reports.json within the website operated by the organization.
If Example Corporation operates https://example.com/, then the
summary report would be found at https://example.com/.well-known/
reports.json.
3. reports.json Structure
The object served from the URL described in Section 2 will have
Content-Type: application/json, and will consist of a single
dictionary object with at least two top-level keys: operations and
reports.
The overall object relationship looks like this:
Gillmor & Gerchick Expires 24 May 2027 [Page 4]
Internet-Draft reports.json November 2026
+------------+ .------------.
| operations | .-->| uri |
+------------+ | | [not_before] |
| urls | | | [not_after] |
| regs +-' '------------'
| reports +-.
+------------+ |
|
| +---------+
'-->| reports |
+---------+
| title |
| date |
| urls |
+---------+
Figure 1: Data Structure For `reports.json`
3.1. reports Content
The reports member is an object where each named member is an object
with the following members:
* title, simple textual string describing the report, and
* date, date object describing the calendar date (year, month, and
day) of the report's publication, and
* urls, an array of URLs that point to the relevant materials for
the report
3.2. operations Content
The operations member is a list of objects, each of which describes
some set of business operations, via the following members:
* urls, an array of URLs, each of which describes a business
operation covered by this object (for example, a job listing),
* regs, an array of "Regulation" objects, described in
Section 3.2.1.
* reports, an array of keys which can be used to point to specific
reports by name
Gillmor & Gerchick Expires 24 May 2027 [Page 5]
Internet-Draft reports.json November 2026
3.2.1. Regulation objects
A Regulations object is one element in an array within an operations
object that indicates the range of regulations that are relevant for
the regulation and the operation.
The only required member for this object is:
* uri, a URI which refers to a specific piece of regulatory guidance
(i.e., a unique identifier that is associated with the
requirements that the operation needs to comply with).
The other defined (but not required) members are:
* not_before, a time marker indicating the calendar date (year,
month, and day) when the regulation first became relevant for the
operation.
* not_after, a time marker indicating the calendar date (year,
month, and day) at which point the regulation is no longer
relevant for the operation.
When both are present, not_after MUST be later than not_before, but
both values MAY be in the future or the past, as a way to indicate
prospective or retrospective compliance.
4. IANA Considerations
IANA should register reports.json in the "Well-Known URIs" registry,
with the following values:
* URI suffix: reports.json
* Change controller: IETF (is this the right choice, if this is an
informational draft? is there a better group to control updates to
this specification?)
* Specification document(s): This document
* Status: provisional (unless we see wider adoption, in which case
we should ask for permanent)
* Related information: Any other examples we want to point to?
5. References
5.1. Normative References
Gillmor & Gerchick Expires 24 May 2027 [Page 6]
Internet-Draft reports.json November 2026
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers
(URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
<https://www.rfc-editor.org/rfc/rfc8615>.
5.2. Informative References
[Auditing-the-Audits]
Gerchick, M., Encarnación, R., Tanigawa-Lau, C.,
Armstrong, L., GutiƩrrez, A., and D. Metaxa, "Auditing the
Audits: Lessons for Algorithmic Accountability from Local
Law 144's Bias Audits", ACM, Proceedings of the 2025 ACM
Conference on Fairness, Accountability, and
Transparency pp. 29-44, DOI 10.1145/3715275.3732004, June
2025, <https://doi.org/10.1145/3715275.3732004>.
[CCPA] "California Consumer Privacy Act Regulations", January
2026, <https://cppa.ca.gov/regulations/pdf/
ccpa_statute_eff_20260101.pdf>.
[CO-SB26189]
"Colorado Senate Bill 26-189", May 2026,
<https://leg.colorado.gov/bills/sb26-189>.
[I-D.ietf-jsonschema-json-schema]
Dusseault, L. M., Wright, A., and H. H. Andrews, "JSON
Schema", Work in Progress, Internet-Draft, draft-ietf-
jsonschema-json-schema-04, 13 October 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-
jsonschema-json-schema-04>.
[JV] Tekuri, S. K., "JSONSchema Validation using Go", n.d.,
<https://github.com/santhosh-tekuri/jsonschema>.
[NYC-LL144]
"Rules of the City of New York: Automated Employment
Decision Tools", April 2023,
<https://codelibrary.amlegal.com/codes/newyorkcity/latest/
NYCrules/0-0-0-138391>.
Gillmor & Gerchick Expires 24 May 2027 [Page 7]
Internet-Draft reports.json November 2026
Appendix A. Test Vectors
A.1. Example reports.json
{
"operations": [
{
"urls": [
"https://example.com/jobs/sysadmin",
"https://example.com/jobs/clerk"
],
"regs": [
{"uri":
"https://codelibrary.amlegal.com/codes/newyorkcity/latest/NYCrules/0-0-0-138391"}
],
"reports": [ "fizz", "sparkle" ]
},
{
"urls": [
"https://example.com/jobs/cfo",
"https://example.com/jobs/cto"
],
"regs": [
{"uri":
"https://codelibrary.amlegal.com/codes/newyorkcity/latest/NYCrules/0-0-0-138391"}
],
"reports": [ "fizz" ]
}
],
"reports": {
"fizz": {
"title": "Fizz Resume Prioritization Service",
"urls": [
"https://fizz.example/bias_audits/aedt_audit_2024.pdf",
"https://fizz.example/bias_audits/aedt_2024_data.tgz"
],
"date": "2024-12-13"
},
"sparkle": {
"title": "Sparkle Video Analytics Assessment",
"urls": [
"https://sparkle.example/video_analytics_2023_audit.pdf"
],
"date": "2024-01-15"
}
}
}
Gillmor & Gerchick Expires 24 May 2027 [Page 8]
Internet-Draft reports.json November 2026
Appendix B. JSON Schema For reports.json
The following JSON Schema (see [I-D.ietf-jsonschema-json-schema]) can
be used to validate an reports.json summary file.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "http://ietf.org/json_schemas/reports_schema.json",
"title": "Report Summary",
"description": "Automated Discovery of Reports",
"type": "object",
"properties": {
"operations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"urls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"uniqueItems": true,
"minItems": 1
},
"regs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"format": "uri"
},
"not_before": {
"type": "string",
"format": "date"
},
"not_after": {
"type": "string",
"format": "date"
}
},
"required": [
"uri"
]
},
Gillmor & Gerchick Expires 24 May 2027 [Page 9]
Internet-Draft reports.json November 2026
"uniqueItems": true,
"minItems": 1
},
"reports": {
"type": "array",
"items": {
"type": "string"
},
"description": "property of top-level 'reports' object",
"uniqueItems": true,
"minItems": 1
}
},
"required": [
"urls",
"regs",
"reports"
]
}
},
"reports": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"title": {
"type": "string"
},
"urls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"uniqueItems": true,
"minItems": 1
}
},
"required": [
"date",
"title",
"urls"
]
}
Gillmor & Gerchick Expires 24 May 2027 [Page 10]
Internet-Draft reports.json November 2026
}
},
"required": [
"operations",
"reports"
]
}
For example, you can validate this using with [JV]:
jv reports-schema.json reports.json
Note that JSON Schema cannot represent foreign key constraints, so
the fact that each /operations/*/reports must reference a named
member of /reports needs to be enforced separately.
Appendix C. Examples of Regulatory Regimes
Please propose more pointers for this subsection!
* [NYC-LL144] established requirements for employers in New York
City to publish reports of audits about automated decision-making
tools used for hiring.
* Colorado's SB 289 [CO-SB26189] requires deployers of automated
decision-making systems to provide consumers with pre-use notices
about the design and deployment of such systems on their websites.
* The California Consumer Privacy Act [CCPA] requires businesses to
create "Risk Assessment Reports" about their use of Automated
Decision-Making Technology (ADMT) as well as pre-use notices about
ADMT use and regular cybersecurity audits.
C.1. Example Regulatory Text
A regulation or law that relies on this mechanism to point toward
relevant reports can cite it using text similar to the following:
Any Covered Organization that has a public website shall publicly
point to the Required Reports associated with each Covered
Operation using a widely understood mechanism such as the
reports.json specification. The Required Reports associated with
this act shall refer to the act as
https://springfield.example/citycouncil/acts/2025/114
(note that this text presumes that the regulation has defined the
terms "Covered Organization", "Covered Operation", and "Required
Reports")
Gillmor & Gerchick Expires 24 May 2027 [Page 11]
Internet-Draft reports.json November 2026
Appendix D. Third-party Hosting
Some entities subject to regulatory obligations might find it
challenging to host a reliably up-to-date reports.json on their
website.
Such an entity may want to contract with a regulatory compliance
consultancy in order to keep this record up-to-date without providing
the consultancy write privileges for the entity's entire website, or
even for material in the website's .well-known/ directory.
Such a consultancy might themselves have multiple clients. The
consultancy could host a repository of their clients' reports.json
files, for example in locations like:
https://consultancy.example/clients/example.com/reports.json
https://consultancy.example/clients/entity1.example/reports.json
And then ask each client to set up a one-time HTTP 302 redirect from
the appropriate location on their site, like so:
https://example.com/.well-known/reports.json redirects to
https://consultancy.example/clients/example.com/reports.json
and
https://entity1.example/.well-known/reports.json redirects to
https://consultancy.example/clients/entity1.example/reports.json
This standard should continue to meet its goals of responsiveness and
discoverability under such a third-party-hosted arrangement.
Acknowledgements
Document History
This section is to be removed before publishing as an RFC.
Changes between audits.json-01 and reports.json-00
This section is to be removed before publishing as an RFC.
* rename from audits.json to reports.json
* add date ranges for operations
* describe third-party hosting
Gillmor & Gerchick Expires 24 May 2027 [Page 12]
Internet-Draft reports.json November 2026
Changes between audits.json-00 and audits.json-01
This section is to be removed before publishing as an RFC.
* added references to CCPA
* align schema test for jv CLI API 0.7
Authors' Addresses
Daniel Kahn Gillmor
American Civil Liberties Union
Email: dkg@fifthhorseman.net
Marissa Kumar Gerchick
American Civil Liberties Union
Email: mgerchick@aclu.org
Gillmor & Gerchick Expires 24 May 2027 [Page 13]