AAP
Application Announcement Protocol
What is Application Announcement Protocol (AAP)?
AAP is a decentralized discovery and metadata publication protocol for applications. Decentralized in the sense that there is no central registry. Feeds are independently hosted and discovered.
AAP 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 application catalogs that can span multiple platforms.
With the increase in web applications, it can be hard to keep track of useful tools. Outside of walled-garden app stores there is no consistent way to present information about applications, and no mechanism to discover newly released applications, or to find curated lists of trusted tools.
AAP provides application 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 its 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:
- Subscribe to applications and view metadata
- Receive updates about applications
- Organize applications in a single location
- Follow individuals or companies for new releases
Developers can build clients such as:
- User-collated application catalogs or stores
- Follow feeds for developers and publishers
- Aggregated discovery platforms.
What isn't AAP?
AAP provides metadata only. It is not a protocol for handling::
- Installation, authentication, or payment.
- Execution or sandboxing environments.
- Global trust or reputation systems.
- Guarantees of safety, quality, or correctness.
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 optimized 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, behavior, or integration points, typically from the perspective of a single application instance. AAP provides a catalog‑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 behavior (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 is guided by these five tenets:
- Easy to understand and get started. Non-engineers 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.
- Use standard web technologies. AAP consists of files that can be hosted on a web server as JSON.
- Require no specialist tools or infrastructure. AAP consists of text files that can be hosted on a service.
- Extensible for advanced information and clients. While easy to start, AAP contains enough keys and capabilities to allow advanced metadata features that may not be used by most clients. The easy things should be easy and the hard things should be possible.
- 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:
- All keys are in camelCase.
- Keys are designed to offer consistent rules that are guessable without checking the documentation and show what is expected.
- Strings are represented as singular nouns, arrays are plural nouns.
- Any key that expects a URL is named [property]Url.
- Any key that expects an email is named [property]Email.
- Any key that expects a date is named [property]Date.
- Any key that expects a enum from a restricted list is named [property]Code.
- These rules combine. A field that expects an array of restricted enums would be called [property]Codes.
- Where possible this convention is used even when there is currently only one key that follows this pattern. For example, brandColor. In the event future color keys are needed these will be written as [property]Color.
- All dates are in ISO 8601 format.
- The JSON structure consists of primitive JSON types and arrays.
- The JSON structure for each application is intentionally flat.
- When a value allows multiple values (tags, categories, etc.) these should be represented as an array of items, not as comma separated values within a string.
- Keys are spelled with American English, e.g. color not colour.
- Extensions beyond the specification are possible, but restricted to the custom object so as not to interfere with future possible extensions.
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. application/json is an acceptable fallback. Clients MUST accept application/json. application/aap+json is preferred.
{
"name": "Minimal AAP Feed",
"description": "A feed containing only the absolute requirements.",
"url": "https://example.com",
"applications": [
{
"name": "Example Application",
"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 keys 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" 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 keys 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 aap.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
| Key | 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 (e.g. 1.0). |
languageCode |
Enum | Optional | IANA language codes |
copyright |
String | Optional | Copyright notice for content in the feed |
owner |
String | Optional | Name of the individual or organization responsible for this feed |
supportUrl |
URL | Optional | Link to support website for the overall feed. |
supportEmail |
Optional | Support contact email for the overall feed. | |
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 applications in the list. |
count |
Int | Optional | Applications 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., updatedDate_desc). |
Applications
SHOULD be ordered by updatedDate descending. Clients MUST
ignore unknown keys.
| Key | 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 application. |
lifecycleCode |
Enum | Optional | Defines the maturity and lifecycle stage of the application. |
supportCode |
Enum | Optional | Defines the level and source of maintenance or support available. |
availabilityCode |
Enum | Optional | Defines whether and how the application can currently be accessed or used. |
distributionCode |
Enum | Optional | Defines how the application is distributed, hosted, or maintained. |
tags |
Array[Str] | Optional | Application 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 application screenshots. |
owner |
String | Optional | Name of the application 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 |
Optional | Support contact email. | |
platformCode |
Enum | Optional | The primary environment or interaction model the application is designed for. |
targets |
Array[str] | Optional | Defines the specific operating systems, runtimes, devices, environments, or host platforms the application explicitly supports or is built to run on. e.g. ["windows", "macos", "linux"] |
updatedDate |
String (ISO 8601) | Optional | Last metadata change date. |
createdDate |
String (ISO 8601) | Optional | First release date. |
version |
String | Optional | Current application version number. |
languageCode |
Enum | Optional | IANA language codes |
copyright |
String | Optional | Application 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 color. |
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:...). |
permissionCodes |
Array[Enum] | Optional | W3C permissions |
capabilities |
Array[Str] | Optional | e.g., ["pwa", "offline"]. |
requirements |
Array[Str] | Optional | Prerequisites for the application to operate. e.g.: ["iOS 15+", "Python 3.9"]. |
Key Details
GUID
The GUID MUST remain stable across:
- version changes
- URL changes
- feed pagination
Clients SHOULD treat the GUID as the canonical identity of the application. It 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 localized versions of the application. This can be a stripped-down version of the main application array, containing only the required keys for a localized instance. This object MUST NOT include the localization key. At a minimum it MUST include:
- languageCode
- url
- name
Versions
An array of previous versions of the application. This can be a stripped-down version of the main application array, containing only the required keys for previous versions. This object MUST NOT include the versions key. At a minimum it MUST include:
- version
- url
- name
lifecycleCode
Defines the maturity and lifecycle stage of the application.
| Value | Description |
|---|---|
| planned | The application has been approved or scheduled for development but has not yet been publicly announced. |
| announcement | The application has been announced but is not yet available for testing or use. |
| development | The application is under active development but not yet ready for public testing. |
| experimental | The application is a research project or experiment with no guarantee of stability or future support. |
| alpha | Early-stage development; features may be incomplete and unstable. |
| beta | Feature-complete but undergoing stabilization and public testing. |
| preview | An early-access build intended for limited evaluation before general release. |
| releaseCandidate | A near-final build undergoing final validation before stable release. |
| active | Stable, fully supported, and recommended for general use. |
| maintenance | Stable and supported, but only receiving critical fixes and security updates. |
| legacy | Still functional but superseded by a newer application or platform. |
| deprecated | Still available, but scheduled for future removal or retirement. |
| endOfLife | No further updates, fixes, or support will be provided. |
| discontinued | Development and official distribution have ceased. |
| withdrawn | Removed from availability or distribution entirely. |
| archived | Preserved in a read-only or historical state. |
| forked | Development has diverged into one or more independent successor projects. |
| abandoned | No active maintenance or development activity is occurring. |
supportCode
Defines the level and source of maintenance or support available.
| Value | Description |
|---|---|
| supported | Fully supported by the publisher or maintainers. |
| community | Supported primarily or exclusively by a volunteer community. |
| limited | Support is restricted in scope, availability, or response time. |
| maintenanceOnly | Only critical fixes or security updates are provided. |
| unsupported | No support is provided. |
| unverified | The authenticity or trustworthiness of the maintainer has not been confirmed. |
| certified | The application has passed formal verification, certification, or compliance review. |
availabilityCode
Defines whether and how the application can currently be accessed or used.
| Value | Description |
|---|---|
| public | Available for general public access and use. |
| private | Restricted to specific authorized users or groups. |
| inviteOnly | Access is limited to approved or invited participants. |
| restricted | Availability is limited by legal, regulatory, geographic, or compliance requirements. |
| pending | Awaiting approval, moderation, or verification before becoming available. |
| suspended | Temporarily unavailable due to maintenance, legal action, or security review. |
| disabled | Intentionally turned off or made inaccessible by the operator. |
| offline | Temporarily unreachable due to operational or infrastructure issues. |
| quarantined | Restricted due to identified security, malware, or trust concerns. |
| withdrawn | Removed from service and no longer accessible. |
distributionCode
Defines how the application is distributed, hosted, or maintained.
| Value | Description |
|---|---|
| primary | The canonical or official distribution source for the application. |
| mirrored | A secondary mirror or replica of another primary distribution source. |
| fork | A modified distribution maintained independently from the original project. |
| communityFork | A community-maintained continuation of an abandoned or discontinued project. |
| vendorHosted | Distributed and hosted directly by the original publisher or vendor. |
| selfHosted | Intended to be deployed and operated by end users or organizations. |
| thirdPartyHosted | Hosted and distributed by an external provider or integrator. |
| aggregated | Distributed as part of a bundled platform, suite, or package collection. |
platformCode
The primary environment or interaction model the application is designed for.
| Value | Description |
|---|---|
| web | Runs in a web browser or web-based runtime environment. |
| mobile | Designed primarily for smartphones or tablets. |
| desktop | Designed primarily for desktop or laptop operating systems. |
| server | Runs as a backend, daemon, hosted service, or infrastructure component. |
| cli | Operates through a command-line or terminal interface. |
| api | Provides machine-to-machine interfaces without a primary graphical UI. |
| library | Intended to be embedded or integrated into other software. |
| extension | Extends functionality of another host application or platform. |
| embedded | Runs on dedicated hardware, appliances, IoT devices, or firmware environments. |
| console | Designed for dedicated gaming or entertainment hardware platforms. |
| vr-ar | Designed for immersive virtual, augmented, or mixed reality environments. |
| ai-agent | Autonomous or semi-autonomous AI-driven systems or workflows. |
| hybrid | Combines multiple platform or runtime models into a unified application. |
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 keys are expected to change.
Custom Extensions
Custom keys MUST reside within an optional
custom object. Each entry requires a
label and a value. The value can be any valid JSON type.
{
"custom": {
"accentColor": {
"label": "Secondary Brand Color",
"value": "#ff0000"
},
"apiUrl": {
"label": "Custom API Gateway",
"value": "https://api.example.com"
}
}
}
Tools and Examples
AAP Validator
Tool for validating aap.json files.
AAP Generator
Tool to generate simple AAP files.
Minimal AAP Client
A minimal AAP client that demonstrates mandatory keys.
Schema JSON file
JSON schema file for the AAP specification.
Minimal Sample aap.json
A minimal sample aap file showing only the mandatory keys in practice. Feel free to develop against this sample file.
Complete Sample aap.json
Sample aap demonstrating the keys in practice. Feel free to develop against this sample file.
Governance
AAP 1.0 was defined by Mobile Appster. Future releases will be defined by the AAP Advisory Board. Membership of the board will be announced on this website.
License
AAP, this documentation and its logos and assets are released under the Apache License, Version 2.0. This means you are able to use the protocol and assets freely in any product without paying royalties or fearing legal repercussions, provided you follow the license's basic requirements.
The key restrictions are:
- Attribution: You must include a copy of the license and retain all original copyright and trademark notices.
- Trademark Restrictions: You cannot use the AAP logo or name in a way that suggests the contributors endorse your specific product.
- No Warranty: If something breaks or causes damage, the contributors are not liable.
- No Liability: You cannot sue the contributors if something doesn't work the way you expected.
In short, you can use the AAP protocol to build a billion-dollar application and keep all the profits. You just need to provide credit in your license file and not sue us if we made a mistake.
Logos and Assets
When advertising availability of an AAP feed you can, but are not required to, use the AAP logo and banner files available to download here: