A Well-Known URI for Software Lifecycle Status

1.1. 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 following terms are used in this document:¶

Software product: A discrete, identifiable unit of software that has a defined vendor or maintainer and a versioned release history.¶

SKU: Stock Keeping Unit. In this document, used to refer to a distinct hardware model or product variant shipped by a vendor (e.g., a specific router model number).¶

Firmware: Software that is embedded in a hardware device and controls its operation. Firmware versions are typically tied to specific hardware models or product families and are updated by the device vendor.¶

Version series: A major or minor version designation under which multiple patch releases may be issued (e.g., "3.2" covering 3.2.0, 3.2.1, 3.2.2, etc.).¶

End-of-life (EOL): A state in which a vendor or maintainer has permanently ceased issuing any updates, including security patches, for a given version series.¶

Long-Term Support (LTS): A designated version series for which the vendor or maintainer commits to an extended support window, typically longer than the standard release lifecycle.¶

Discontinued: A hardware product that is no longer manufactured or sold. A discontinued product MAY still receive firmware security updates for existing deployments; this is distinct from end-of-life.¶

Consuming tool: Any software system that retrieves and processes a software-status.json resource, including security scanners, SCA tools, package managers, and monitoring systems.¶

2.1. Location and Retrieval

A software vendor or maintainer that wishes to publish lifecycle status information for software associated with a domain SHOULD publish a software-status.json resource at the Well-Known URI:¶

https://example.com/.well-known/software-status.json

The resource MUST be served over HTTPS. HTTP retrieval MAY be supported for compatibility but consuming tools SHOULD prefer HTTPS and SHOULD warn or fail if only HTTP is available.¶

The resource MUST be served with a Content-Type of application/json.¶

If no lifecycle information is available or the vendor has not adopted this convention, the server SHOULD return HTTP 404. Consuming tools MUST treat a 404 response as "no declaration available" and fall back to other methods. Consuming tools MUST NOT treat a 404 as evidence that the software is end-of-life.¶

2.2. Caching

The resource SHOULD include standard HTTP caching headers. A max-age of 604800 (seven days) is RECOMMENDED for resources that are infrequently updated. Consuming tools SHOULD respect Cache-Control and Expires headers.¶

In the absence of explicit caching headers, consuming tools SHOULD cache a successfully retrieved resource for no fewer than 24 hours and no more than 30 days.¶

Vendors with large product catalogs (see Section 4.5) whose software-status.json resource is updated frequently SHOULD set a shorter max-age (e.g., 86400, one day) and include an ETag to allow consuming tools to perform conditional GET requests.¶

3.1. Root Object

The root object MUST contain the following fields:¶

schema_version (string, REQUIRED):

The version of this schema. This document defines version "1.0". Consuming tools that encounter an unrecognized schema version SHOULD process fields they recognize and ignore fields they do not.¶

vendor (string, REQUIRED):

The name of the organization or individual responsible for the software's support lifecycle. In multi-product mode, this is the vendor organization name. In single-product mode, this is the product vendor.¶

In single-product mode (when products is absent), the root object MUST also contain:¶

name (string, REQUIRED):

The human-readable name of the software product.¶

versions (array, REQUIRED):

An array of version entry objects as described in Section 4.2. MUST contain at least one entry. SHOULD include all version series for which the vendor has a defined support position, including EOL versions.¶

The root object MAY contain the following fields in either mode:¶

specification (string):

A URI identifying the specification that defines this schema. When present, consuming tools MAY use this field to verify schema compatibility or route processing to a version-appropriate parser. For resources conforming to this document, the value SHOULD be the IETF Datatracker URI for this Internet-Draft or its successor RFC (e.g., "https://datatracker.ietf.org/doc/draft-mcconnell-software-status-wellknown/"). This field is self-documenting: it allows a human or tool encountering an unfamiliar software-status.json resource to locate the governing specification without prior knowledge.¶

homepage (string):

A URI for the vendor's primary website. In single-product mode, MAY refer to the product page specifically.¶

source (string):

A URI for the software's canonical source repository. Typically absent in multi-product mode unless the vendor publishes a monorepo.¶

package_identifiers (object):

In single-product mode: a map of package ecosystem names to the identifier used in that ecosystem. See Section 4.4. SHOULD NOT be present in multi-product mode; use per-product package_identifiers in each product entry instead.¶

release_cycle_url (string):

A URI for the vendor's official support lifecycle or release policy page.¶

last_updated (string):

An ISO 8601 date string indicating when this resource was last reviewed or updated (e.g., "2026-04-25"). Consuming tools MAY use this field to decide whether to re-fetch the resource regardless of caching policy.¶

products (array):

When present, indicates multi-product mode. An array of product entry objects as described in Section 4.5. When this field is present, consuming tools MUST use product entries for lifecycle lookups and SHOULD NOT use root-level name and versions for product matching.¶

3.2. Version Entries

Each object in the versions array (whether at the root level in single-product mode, or within a product entry in multi-product mode) represents one version series and MUST contain the following fields:¶

version (string, REQUIRED):

The version series identifier. This MAY be a specific version number ("3.2"), a major version with wildcard ("2.x"), a named track ("LTS 22.04"), or any string that meaningfully identifies the series to the vendor's users. For firmware, this SHOULD be the firmware version string as displayed in the device's management interface.¶

status (string, REQUIRED):

The current support status of this version series. MUST be one of the values defined in Section 4.3.¶

Each version entry MAY contain the following fields:¶

release_date (string):

An ISO 8601 date on which this version series reached general availability.¶

support_ends (string or null):

An ISO 8601 date on which support for this version series is scheduled to end. A value of null indicates no currently planned end date. SHOULD be present for all version series where a planned end date is known.¶

eol_date (string):

An ISO 8601 date on which this version series reached end-of-life. This field records a past event; support_ends records a future one. SHOULD be present when status is "eol" and the date is known.¶

lts (boolean):

true if this version series is designated as Long-Term Support. Defaults to false if absent.¶

notes (string):

A human-readable note providing additional context about this version entry. Consuming tools MAY surface this to users but MUST NOT rely on its content for programmatic decisions.¶

3.3. Status Values

The status field MUST be one of the following values:¶

"active":

The version series is fully supported. The vendor intends to issue bug fixes, security patches, and potentially new features.¶

"lts":

The version series is designated Long-Term Support. The vendor commits to issuing security patches (and possibly bug fixes) for an extended period.¶

"security-only":

The version series is no longer receiving general bug fixes or new features, but security vulnerabilities are still being patched.¶

"eol":

The version series has reached end-of-life. No further patches of any kind will be issued, including security patches.¶

"unmaintained":

The software project has been abandoned by its original maintainer. No patches are expected, but the project has not been formally declared end-of-life.¶

Additional status values MAY be defined in future revisions of this document. Consuming tools that encounter an unrecognized status value SHOULD treat it as equivalent to "unknown" and note the unrecognized value in any user-facing output.¶

3.4. Package Identifiers

The optional package_identifiers object maps package ecosystem names to the string identifier used in that ecosystem. Known ecosystem names include, but are not limited to:¶

A value of null for a given key indicates the software is not distributed through that ecosystem.¶

3.5. Multi-Product Resources

4.1. Discovery

To retrieve lifecycle status for software associated with a known domain, a consuming tool SHOULD:¶

1. Construct the URI https://{domain}/.well-known/software-status.json¶
2. Issue an HTTP GET request with an Accept: application/json header¶
3. Treat a 2xx response containing valid JSON as a successful retrieval¶
4. Treat a 404 or 410 response as "no declaration" and fall back¶
5. Treat other error responses (5xx, timeouts) as transient failures; retry with exponential backoff before treating as unavailable¶
6. Check for the presence of a products field to determine whether to use single-product or multi-product processing (see Section 4.5)¶

4.2. Version Matching

When matching an installed version against the versions array (whether at the root level or within a product entry), consuming tools SHOULD use the following logic:¶

1. Attempt an exact match on the version field¶
2. If no exact match, attempt a prefix match: an installed version of 3.2.7 matches a version series of 3.2¶
3. If no prefix match, attempt a major-version match: 3.2.7 matches 3.x¶
4. If no match is found, treat the version's lifecycle status as unknown¶

When multiple entries match, consuming tools SHOULD prefer the most specific match (exact > prefix > major-version).¶

4.3. Conflict Resolution

When a consuming tool has lifecycle data for a product from multiple sources (e.g., a third-party database and a software-status.json resource), data retrieved from software-status.json SHOULD be treated as authoritative and given precedence, as it represents a declaration by the party responsible for the software's support policy.¶

5.1. Authenticity

The software-status.json resource is served over HTTPS and inherits the authenticity guarantees of the TLS connection. A consuming tool that retrieves the resource over HTTPS from the vendor's canonical domain can be reasonably confident that the content reflects the vendor's intent.¶

Consuming tools MUST NOT retrieve this resource over plain HTTP and treat it as authoritative. Consuming tools SHOULD validate that the hostname of the retrieval URI matches the domain associated with the software in question.¶

5.2. Denial of Service

A consuming tool that retrieves software-status.json resources at scale SHOULD implement rate limiting, caching, and exponential backoff to avoid placing undue load on vendor infrastructure.¶

For multi-product resources, a consuming tool that needs lifecycle status for multiple products from the same vendor SHOULD retrieve the resource once and process all required products from the cached response, rather than issuing repeated requests.¶

5.3. Misleading Declarations

This mechanism relies on vendors publishing accurate information. A vendor could theoretically publish a software-status.json that misrepresents the support status of a product — for example, declaring an EOL product as "active" to discourage users from migrating, or omitting a product from the products array to avoid acknowledging its EOL status. Consuming tools SHOULD note the source of lifecycle determinations in user-facing output so that users can evaluate the claim in context.¶

Consuming tools that maintain independent lifecycle databases MAY flag discrepancies between their own records and a vendor-published software-status.json for human review.¶

The absence of a product from a vendor's products array MUST NOT be interpreted as confirmation that the product is end-of-life or unsupported. It indicates only that the vendor has not published a declaration for that product via this mechanism.¶

5.4. Privacy

Retrieving software-status.json from a vendor's domain may reveal to that vendor that a consuming tool is checking lifecycle status, potentially disclosing information about what software is deployed in an organization. Consuming tools operating in sensitive environments SHOULD consider whether direct retrieval is appropriate or whether a privacy-preserving intermediary (such as a shared cache or mirroring service) should be used.¶

For multi-product resources, a single retrieval reveals interest in the vendor's products generally, but does not disclose which specific SKU or version is deployed. This is a privacy improvement over per-product endpoints, which would reveal the specific product being queried.¶

6.1. Well-Known URI Registration

IANA is requested to register the following Well-Known URI in the "Well-Known URIs" registry established by [RFC8615]:¶

URI suffix:

software-status.json¶

Change controller:

IETF¶

Specification document(s):

This document¶

Related information:

This URI returns a JSON document describing the software lifecycle status for products associated with the host. The format is defined in Section 4 of this document. The resource MAY describe a single product or a catalog of multiple products or hardware SKUs.¶

A.1. Minimal Single-Product Resource

{
  "schema_version": "1.0",
  "specification": "https://datatracker.ietf.org/doc/draft-mcconnell-software-status-wellknown/",
  "name": "ExampleDB",
  "vendor": "Example Software Inc.",
  "versions": [
    {
      "version": "5.0",
      "status": "active",
      "support_ends": null
    }
  ]
}

A.2. Multi-Version Single-Product Resource with EOL History

{
  "schema_version": "1.0",
  "name": "ExampleDB",
  "vendor": "Example Software Inc.",
  "homepage": "https://example.com/db",
  "package_identifiers": {
    "apt": "exampledb-server",
    "docker": "exampleinc/exampledb"
  },
  "versions": [
    {
      "version": "5.0",
      "release_date": "2025-03-01",
      "status": "active",
      "support_ends": null,
      "lts": false
    },
    {
      "version": "4.2",
      "release_date": "2023-06-15",
      "status": "lts",
      "support_ends": "2027-06-15",
      "lts": true,
      "notes": "LTS release — security and critical bug fixes through June 2027"
    },
    {
      "version": "4.0",
      "release_date": "2022-01-10",
      "status": "security-only",
      "support_ends": "2026-01-10",
      "lts": false
    },
    {
      "version": "3.x",
      "release_date": "2019-04-01",
      "status": "eol",
      "eol_date": "2024-04-01",
      "support_ends": "2024-04-01",
      "lts": false
    }
  ],
  "release_cycle_url": "https://example.com/support-policy",
  "last_updated": "2026-04-25"
}

A.3. Multi-Product Resource: Network Equipment Vendor

The following example illustrates a network equipment vendor publishing lifecycle status for multiple hardware SKUs from a single endpoint. This pattern is appropriate for vendors such as router, switch, or wireless access point manufacturers that ship dozens to hundreds of distinct hardware models, each with its own firmware version history.¶

Note the use of product_type: "hardware-firmware" and the discontinued flag, which allows consuming tools to distinguish between hardware that is no longer sold and firmware that is no longer patched — two related but distinct conditions that affect operator decisions differently.¶

{
  "schema_version": "1.0",
  "specification": "https://datatracker.ietf.org/doc/draft-mcconnell-software-status-wellknown/",
  "vendor": "Example Networks Inc.",
  "homepage": "https://network-vendor.example.com",
  "release_cycle_url": "https://network-vendor.example.com/end-of-life",
  "last_updated": "2026-04-25",
  "products": [
    {
      "product_id": "ENI-GW-PRO",
      "name": "Example Gateway Pro",
      "sku": "ENI-GW-PRO",
      "product_type": "hardware-firmware",
      "platform": "arm64",
      "discontinued": false,
      "homepage": "https://network-vendor.example.com/products/gw-pro",
      "versions": [
        {
          "version": "5.0",
          "release_date": "2025-09-01",
          "status": "active",
          "support_ends": null,
          "notes": "Current production firmware"
        },
        {
          "version": "4.x",
          "release_date": "2023-03-15",
          "status": "security-only",
          "support_ends": "2026-09-01"
        },
        {
          "version": "3.x",
          "release_date": "2021-01-10",
          "status": "eol",
          "eol_date": "2025-01-10"
        }
      ]
    },
    {
      "product_id": "ENI-GW-SE",
      "name": "Example Gateway SE",
      "sku": "ENI-GW-SE",
      "product_type": "hardware-firmware",
      "platform": "arm64",
      "discontinued": false,
      "versions": [
        {
          "version": "5.0",
          "release_date": "2025-09-01",
          "status": "active",
          "support_ends": null
        },
        {
          "version": "4.x",
          "release_date": "2023-06-01",
          "status": "security-only",
          "support_ends": "2026-09-01"
        }
      ]
    },
    {
      "product_id": "ENI-AP-AX",
      "name": "Example Access Point AX",
      "sku": "ENI-AP-AX",
      "product_type": "hardware-firmware",
      "platform": "mips",
      "discontinued": true,
      "notes": "Hardware discontinued March 2025; firmware security patches continue through 2027",
      "versions": [
        {
          "version": "6.x",
          "release_date": "2022-11-01",
          "status": "security-only",
          "support_ends": "2027-03-01"
        },
        {
          "version": "5.x",
          "release_date": "2020-06-01",
          "status": "eol",
          "eol_date": "2024-06-01"
        }
      ]
    },
    {
      "product_id": "ENI-SW-24",
      "name": "Example Switch 24-Port",
      "sku": "ENI-SW-24",
      "product_type": "hardware-firmware",
      "platform": "arm32",
      "discontinued": false,
      "versions": [
        {
          "version": "3.x",
          "release_date": "2024-02-01",
          "status": "active",
          "support_ends": null
        }
      ]
    }
  ]
}

B.1. Motivation

Many software projects are distributed as source code and do not have a corresponding web domain from which a Well-Known URI could be served. Open-source libraries, developer tools, and components published to package registries often have a repository URL as their primary identity, not a product domain.¶

For these projects, a file committed to a predictable location within the repository serves the same purpose as the Well-Known URI.¶

B.2. Location

The resource SHOULD be placed at:¶

{repository-root}/.github/software-status.json

The .github/ directory is an established convention on major version- control platforms for repository-level metadata. This location is intentionally analogous to .github/SECURITY.md, .github/FUNDING.yml, and similar files.¶

B.3. Discovery

Consuming tools that resolve a software package to a GitHub-hosted repository SHOULD check for the presence of this file at the raw content URL:¶

https://raw.githubusercontent.com/{owner}/{repo}/HEAD/.github/software-status.json

A 404 response MUST be treated as "no declaration available". A 200 response with valid JSON MUST be processed according to the schema defined in Section 4.¶

B.4. Schema

The .github/software-status.json resource uses the same JSON schema as defined in Section 4, with one addition: the source field at the root object SHOULD be set to the canonical repository URI. The products array MAY be used in repository-hosted resources for projects that maintain multiple independently versioned components within a single repository (monorepos).¶

B.5. Precedence

When a project has both a Well-Known URI resource and a repository-hosted resource, consuming tools SHOULD prefer the Well-Known URI, as it is served from infrastructure explicitly controlled by the vendor and subject to the HTTPS authenticity guarantees described in Section 6.¶

B.6. Example

{
  "schema_version": "1.0",
  "name": "example-lib",
  "vendor": "Example Org",
  "source": "https://github.com/example/example-lib",
  "package_identifiers": {
    "pypi": "example-lib",
    "npm": null
  },
  "versions": [
    {
      "version": "2.0",
      "release_date": "2025-01-01",
      "status": "active",
      "support_ends": null
    },
    {
      "version": "1.x",
      "release_date": "2022-06-01",
      "status": "eol",
      "eol_date": "2025-06-01"
    }
  ],
  "last_updated": "2026-04-25"
}