AAP Specification | Application Announcement Protocol

What is Application Announcement Protocol (AAP)

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

Clients can:

Subscribe to applications and view metadata.
Receive updates about applications.
Organize apps in a single location.
Follow individuals or companies for new releases.

Enables creation of:

Third party app store clients.
User-collated application catalogs.
Developer/Publisher follow-feeds.
Aggregated discovery platforms.

What isn't AAP

AAP handles metadata only. It specifically does not define:

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.

Design Principles

Use standard web technologies.
Easy to start with low overhead.
Requires no specialist tools to make feeds.
Clean structures to make hand-editing easy.
Extensible for advanced information and clients.

Note: Feeds MAY aggregate applications from multiple publishers. Clients MUST treat each application object as the unit of authority.

Hosting an AAP file

The system consists of a single file aap.json hosted at /.well-known/aap.json.

HTML Redirection

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" />

The .well-known path takes priority. Files MUST be UTF-8 encoded and served with MIME type application/aap+json.

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"`

Specification

The aap.json file is a single plain text json file hosted on the service web server.

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 larger more complex versions can be machine generated to support more complex features including pagination

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.
`category`	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.
`category`	Array[Str]	Recommended	Categories for this app.
`cost`	Double	Optional	Cost of the application.
`currency`	String	Optional	The currency unit.
`pricingModel`	Enum	Optional	subscription, one-off.
`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.
`screenshots`	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.
`publisherDidID`	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.
`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"].

Key Fields

GUID

The GUID MUST remain stable across:

version changes
URL changes
feed pagination

Clients SHOULD treat GUID as the canonical identity of the application. If omitted, clients MAY fall back to the application's URL, though this is not guaranteed to remain stable. 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 SHOULD include:

language
url
name

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 SHOULD include:

version
url
name

Pagination & Sorting

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

The metadata section SHOULD 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 JSON type.

{
  "custom": {
    "accent_color": {
      "label": "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 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.