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`	Email	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`	Email	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: