The Open Contributions Descriptor

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 21 September 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.¶

Table of Contents

1. Introduction

Organizations participate in the open ecosystem in many different ways, including by maintaining software, publishing datasets, contributing to standards, documenting governance, and supporting external communities. Today, this information is usually fragmented across websites, forge hosting platforms, policy pages, and standards organization portals.¶

The Open Contributions Descriptor (OCD) defines a single JSON [RFC8259] document that aggregates this information in a predictable format. OCD is intended for both human readers and automated tooling. Example use cases include:¶

• organizational open-source program office inventories;¶
• cataloging of open data and public APIs;¶
• ecosystem mapping and stewardship analysis;¶
• transparency around standards participation; and¶
• automated discovery of contribution entry points and contact channels.¶

The design goals of OCD are:¶

• provide a single discovery endpoint for organizational open activities;¶
• support both human discovery and machine automation;¶
• remain extensible without breaking compatibility; and¶
• allow partial adoption where only some sections are populated.¶

2. Conventions and Definitions

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.¶

The underlying representation of OCD is JSON as defined by [RFC8259]. Date and date-time values use RFC 3339 formatting [RFC3339].¶

3. Publication and Discovery

An OCD document is intended to be published at the following location:¶

https://<organization-domain>/.well-known/open-contributions.json

The use of the /.well-known/ path follows the general mechanism defined in [RFC8615]. Organizations MAY publish the same content at additional locations, but the well-known location is the canonical discovery endpoint.¶

4. Document Model

An OCD document is a UTF-8 encoded JSON object. Unknown members MAY appear in an OCD document. Consumers MUST ignore members they do not understand, unless a profile or extension explicitly defines stricter processing rules.¶

The top-level object has the following members.¶

5. Validation and Processing Rules

An OCD processor:¶

• MUST parse the document as JSON;¶
• MUST treat spec_version, generated_at, and organization as required top-level members;¶
• MUST ignore unknown members;¶
• SHOULD validate date-time values against RFC 3339;¶
• SHOULD validate license identifiers against SPDX when such validation is available; and¶
• SHOULD preserve unrecognized extension content when transforming or proxying an OCD document.¶

6. Example

The following example illustrates an OCD document.¶

{
  "spec_version": "1.0",
  "generated_at": "2026-02-23T09:00:00Z",
  "organization": {
    "name": "Example Organization",
    "domain": "example.org",
    "description": "An organization contributing to open source software, open data, and open standards.",
    "country": "LU",
    "links": {
      "homepage": "https://example.org",
      "opensource_page": "https://example.org/open",
      "github_org": "https://github.com/example-org"
    }
  },
  "contacts": {
    "opensource": {
      "email": "opensource@example.org"
    },
    "security": {
      "url": "https://example.org/.well-known/security.txt"
    },
    "community": {
      "email": "community@example.org"
    }
  },
  "policies": {
    "code_of_conduct": "https://example.org/code-of-conduct",
    "contributing": "https://example.org/contributing",
    "vulnerability_disclosure": "https://example.org/security",
    "license_policy": "https://example.org/open/licensing"
  },
  "projects": [
    {
      "name": "Vulnerability Lookup",
      "description": "An open platform to correlate and explore vulnerability intelligence.",
      "status": "active",
      "repository": {
        "url": "https://github.com/example-org/vulnerability-lookup",
        "license": "AGPL-3.0",
        "type": "git",
        "clone": "https://github.com/example-org/vulnerability-lookup.git",
        "tests": "https://ci.example.org/job/vulnerability-lookup/"
      },
      "links": {
        "project_page": "https://www.vulnerability-lookup.org",
        "homepage": "https://example.org/projects/vulnerability-lookup",
        "documentation": "https://docs.vulnerability-lookup.org",
        "demo": "https://vulnerability.example.org",
        "releases": "https://github.com/example-org/vulnerability-lookup/releases",
        "community": "https://matrix.to/#/#vulnlookup:matrix.org",
        "metadata": {
          "openapi": "https://vulnerability.example.org/openapi.json"
        }
      },
      "participate": {
        "issues": "https://github.com/example-org/vulnerability-lookup/issues",
        "good_first_issues": "https://github.com/example-org/vulnerability-lookup/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22",
        "chat": "https://matrix.to/#/#vulnlookup:matrix.org",
        "docs": "https://docs.vulnerability-lookup.org"
      },
      "governance": {
        "maintainers": [
          "maintainers@example.org"
        ],
        "codeowners": "https://github.com/example-org/vulnerability-lookup/blob/main/CODEOWNERS"
      },
      "release": {
        "changelog": "https://github.com/example-org/vulnerability-lookup/releases",
        "security_policy": "https://github.com/example-org/vulnerability-lookup/security/policy"
      },
      "tags": [
        "security",
        "vulnerability-management",
        "open-source"
      ]
    }
  ],
  "open_data": [
    {
      "name": "Daily Threat Indicators",
      "description": "Open dataset of curated threat intelligence indicators.",
      "license": "CC-BY-4.0",
      "publisher": "Example Organization",
      "urls": {
        "landing_page": "https://example.org/data/threat-indicators",
        "download": "https://example.org/data/threat-indicators/latest.json",
        "api": "https://example.org/api/threat-indicators"
      },
      "formats": [
        "json",
        "csv"
      ],
      "update_frequency": "daily",
      "schema": "https://example.org/data/threat-indicators/schema.json",
      "tags": [
        "open-data",
        "cybersecurity",
        "threat-intelligence"
      ]
    }
  ],
  "open_standards": [
    {
      "body": "IETF",
      "working_groups": [
        "openpgp",
        "sidrops"
      ],
      "contributions": [
        {
          "type": "draft-author",
          "title": "Example Secure Exchange Format",
          "url": "https://datatracker.ietf.org/doc/draft-example-secure-exchange/"
        },
        {
          "type": "implementation",
          "title": "Reference implementation",
          "url": "https://github.com/example-org/secure-exchange"
        }
      ],
      "contacts": [
        {
          "email": "standards@example.org"
        }
      ]
    }
  ],
  "relationships": [
    {
      "type": "co_maintains",
      "description": "We co-maintain the upstream project with the foundation and another OSPO.",
      "since": "2023-05-01",
      "target": {
        "kind": "project",
        "name": "Upstream Tooling",
        "url": "https://upstream.example.net/tooling",
        "ocd": "https://upstream.example.net/.well-known/open-contributions.json",
        "project": {
          "repository_url": "https://github.com/upstream/tooling",
          "homepage": "https://upstream.example.net/tooling",
          "license": "MPL-2.0"
        }
      },
      "evidence": [
        "https://github.com/upstream/tooling/blob/main/MAINTAINERS.md",
        "https://github.com/upstream/tooling/graphs/contributors"
      ],
      "contacts": [
        {
          "email": "opensource@example.org"
        }
      ],
      "tags": [
        "governance",
        "maintenance"
      ]
    }
  ],
  "extensions": {}
}

7. Security Considerations

OCD documents are descriptive metadata and do not directly grant privileges or convey authority. However, consumers might use OCD data to drive discovery, ranking, trust decisions, or automation. A malicious or compromised publisher could therefore provide inaccurate metadata.¶

Consumers SHOULD treat OCD content as unverified assertions unless backed by independently validated evidence. Consumers that act automatically on OCD content SHOULD apply origin authentication, transport security, and local policy before making trust or security decisions.¶

Publishing contact information can increase discoverability but can also increase unwanted scraping, profiling, or spam. Publishers SHOULD consider the privacy impact of any personal data included in OCD documents.¶

8. IANA Considerations

IANA is requested to register the well-known URI suffix open-contributions.json in the "Well-Known URIs" registry established by RFC 8615.¶

The registry entry should include the following information:¶

• URI suffix: open-contributions.json¶
• Change controller: OSSBASE¶
• Specification document(s): This document¶

This well-known resource is used to discover a JSON document describing an organization's open contributions profile.¶

A registration request for this well-known URI suffix has been filed and is tracked at: https://github.com/protocol-registries/well-known-uris/issues/78¶

Appendix A. References

Author's Address