AAP Logo AAP

Application Announcement Protocol

What is Application Announcement Protocol (AAP)

AAP is a decentralized discovery and metadata publication protocol for applications. It allows you to announce the availability of applications (web, native or otherwise), and allows clients to manage, organize and discover new applications.

Why would I use AAP?

AAP provides machine-readable application discovery for agents, aggregators, and cross-platform catalogs.

With the increase in web applications, it can be hard to keep track useful tools. Outside of walled gardened appstores There is no consistent way to present information about applications, and no mechanism to discover when new applications are released, or to find curated lists of trusted tools.

AAP provides app creators with a consistent way of structuring metadata about their applications to make it easier for users to discover, curate and manage applications.

AAP does not provide a central registry of tools or feeds, although third parties may choose to use AAP to create such a service. Due to it's open nature, users will always be able to subscribe to any independently provided feed without being dependent on a single central authority

What can you do with AAP

Users can: Developers can built clients that might be:

What isn't AAP

AAP provides metadata only. It specifically is not a protocol to handle:

Trust decisions are delegated to clients, aggregators, and users. AAP provides the mechanisms for feed integrity, identity, and optional publisher identification.

AAP does not aim to replace existing web standards.

RSS/Atom syndicate time‑ordered content such as articles, posts, or media. While they could be used to announce software releases, their data model is optimised for human‑consumable content rather than structured application metadata. AAP focuses specifically on application identity, rich metadata, and long‑lived discovery, rather than episodic content updates.

OpenSearch and Web Manifests define how applications and websites describe their own capabilities, behaviour, or integration points, typically from the perspective of a single application instance. AAP provides a catalogue‑oriented feed designed to describe multiple applications, versions, or releases in a consistent, machine‑readable way that can be aggregated, indexed, and curated by third‑party clients.

AAP is concerned with announcing and discovering applications, not rendering content (RSS/Atom) or describing runtime behaviour (manifests). These standards can be used together: an AAP entry may reference RSS feeds, manifests, repositories, or other resources as part of an application’s metadata.

Principles

AAP aims to obey these five tenets:

  1. Easy to understand and get started. Non-engineers users should be able to create and understand an aap.json file. The most basic possible aap.json file is simple and easy to get started with.
  2. Use standard web technologies. AAP consists of files that can be hosted on websites in json.
  3. Require no specialist tools or infrastructure. AAP consists of text files that can be hosted on a website.
  4. Extensible for advanced information and clients. While easy to start, AAP contains enough fields and capabilities to allow advanced metadata features that may not be used by most clients, but are possible. The easy things are easy and the hard things are possible.
  5. Future versions must maintain backwards compatibility. New versions of the specification will add additional capabilities, and will not introduce breaking changes.

To assist with these five tenets, AAP has developed a number of conventions:

Getting Started

The simplest way of offering an AAP feed is to put a single json file aap.json on your server at ./well-known/aap.json

Files MUST be UTF-8 encoded and SHOULD be served with MIME type application/aap+json.

{
  "name": "Minimal App Feed",
  "description": "A feed containing only the absolute requirements.",
  "url": "https://example.com",
  "applications": [
    {
      "name": "Example App",
      "description": "A simple application entry.",
      "url": "https://example.com/app",
      "guid": "https://example.com/app/unique-id-123"
    }
  ]
}
                

AAP clients scan this file to learn about the applications you offer, receiving updates when you update or add new applications

AAP offers other optional fields listed below for services that want to provide more advanced information.

If the well-known location is not available, specify the path in the HTML <head>:

<meta name="application-announcement-protocol-location" 
      content="https://example.com/feeds/aap.json" />

If a different path is set in the HTML <head> and a file is available at .well-known/aap.json the file MUST take priority.

HTTP Response Headers

Required: HTTPS is mandatory.

Header Requirement
Content-Type SHOULD be application/aap+json
Cache-Control Recommended (max-age)
ETag / Last-Modified Recommended for efficient polling
Link <url>; rel="aap"

Feed Specification

The aap.json file is a single plain text json file hosted on the service web server at ./well-known/aap.json

It consists of a series of metadata fields at the root of the json object and an applications array. There are a small number of mandatory values, some recommended but not mandatory values and a larger number of optional values.

The simplest, smallest app.json file could be written by hand in a few minutes, but more complex versions can be machine generated to support more complex features.

Metadata

Field Type Status Description
name String Mandatory The name of the service/feed. It's how people refer to the service.
description String Mandatory Description of the feed.
url URL Mandatory The URL to the HTML website corresponding to the feed.
iconUrl URL Recommended Square image (gif, jpeg, png, svg, webp) that can be displayed on the channel.
categories Array[Str] Recommended Categories for the overall service.
aapVersion String Optional Protocol version (Default: 1.0).
language Enum Optional W3C language codes
copyright String Optional Copyright notice for content in the feed
owner String Optional Name of the individual or organisation responsible for this feed
supportUrl URL Optional Link to support website.
supportEmail Email Optional Support contact email.
horizontalFeatureImageUrl URL Optional 16:9 rectangle image.
verticalFeatureImageUrl URL Optional 9:16 rectangle image.
didId String Optional Decentralized ID of the feed owner(did:web:...).
total Int Optional Total apps in the list.
count Int Optional Apps in current file.
next URL Optional URL for the next page of results.
previous URL Optional URL for the previous page of results.
sort String Optional Sorting order (e.g., dateUpdated_desc).

Applications

Ordered by dateUpdated descending. Clients MUST ignore unknown fields.

Field Type Status Description
name String Mandatory The name of the application.
description String Mandatory Short description of the application.
url URL Mandatory Main URL to run or install the application itself.
guid String/URI Mandatory Stable identifier. MUST be globally unique.
iconUrl URL Recommended Square image (gif, jpeg, png, svg, webp) that can be displayed against the application.
categories Array[Str] Recommended Categories for this app.
status Enum Optional active, deprecated, withdrawn.
tags Array[Str] Optional App capabilities tags.
keywords Array[Str] Optional Keywords for classification.
horizontalFeatureImageUrl URL Optional 16:9 feature image.
verticalFeatureImageUrl URL Optional 9:16 feature image.
screenshotUrls Array[URL] Optional URLs to app screenshots.
owner String Optional Name of the app creator/owner.
size Number Optional Size in bytes.
license String Optional Software license (e.g., MIT).
publisher String Optional Individual or company name.
publisherUrl URL Optional Unique URL for the publisher.
publisherDid String Optional Publisher decentralized ID.
sourceUrl URL Optional Code repository URL.
docsUrl URL Optional Documentation URL.
supportUrl URL Optional Support assistance URL.
promptUrl URL Optional AI prompt path if applicable.
commentsUrl URL Optional User discussion URL.
ratingUrl URL Optional Reviews/Rating URL.
privacyUrl URL Optional Privacy policy URL.
termsUrl URL Optional Terms and conditions URL.
changelog String Optional Text list of changes.
changelogUrl URL Optional URL to list of changes.
supportEmail Email Optional Support contact email.
platform Enum Optional web, ios, android, windows, macos, linux, cli, api, game, ai-agent, extension, library
dateUpdated ISO 8601 Optional Last metadata change date.
dateCreated ISO 8601 Optional First release date.
version String Optional Current app version number.
language Enum Optional W3C language codes
copyright String Optional App copyright notice.
ageScheme String Optional Rating scheme (e.g. PEGI).
ageValue String Optional Specific age rating value.
brandColor String Optional Hex value indicating the brand's colour.
contentDescriptors Array[Str] Optional e.g., ["Violence"].
localization Array[Obj] Optional Localized application objects.
versions Array[Obj] Optional Archive of previous versions.
checksum String Optional Hash (e.g. sha256:...).
permissions Array[Enum] Optional W3C permissions
capabilities Array[Str] Optional e.g., ["pwa", "offline"].
requirements Array[Str] Optional Prerequisites for the application to operate. eg: ["iOS 15+", "Python 3.9"].

Field Details

GUID

The GUID MUST remain stable across:

Clients SHOULD treat GUID as the canonical identity of the application. MUST be globally unique.

MUST NOT be reused for a different application.

SHOULD be a URI under a domain the publisher controls

Localization

An array of localised version of the application. This can be stripped down version of the main application array, containing only the key fields for a localized instance. This object MUST NOT include the localization key. At a minimum it MUST include:

Versions

An array of previous version of the application. This can be stripped down version of the main application array, containing only the key fields for previous version. This object MUST NOT include the versions key. At a minimum it MUST include:

Pagination & Sorting

If a feed becomes large it SHOULD offer pagination.

Feeds SHOULD use stable ordering across pages. Cursor-based pagination is RECOMMENDED. Cursor values MUST be treated as opaque by clients.

The metadata section MUST remain identical across paginated pages so clients can identify them as belonging to the same feed. Only the applications array and pagination fields are expected to change.

Custom Extensions

Custom fields MUST reside within an optional custom object. Each entry requires a label and a value. Value can be any valid JSON type.

{
  "custom": {
    "accent_color": {
      "label": "Secondary Brand Color",
      "value": "#ff0000"
    },
    "api_endpoint": {
      "label": "Custom API Gateway",
      "value": "https://api.example.com"
    }
  }
}

Tools and Examples

AAP Validator

AAP Validator Validator tool to validate aap.json files.

AAP Sample Client

Sample Client A sample AAP client, demonstrating how the clients can use the aap.json file.

AAP Minimal Client

Minimal Client A minimal AAP client that focuses only on mandatory fields.

AAP Generator

AAP Generator Tool to generate simple AAP files.

Minimal Sample aap.json

Minimal Sample AAP file A minimal sample aap file showing only the mandatory fields in practice. Feel free to develop against this sample file.

Complete Sample aap.json

Sample AAP file Sample aap file showing the fields in practice. Feel free to develop against this sample file.