Status: Blue Jetty Technical Specification 1.0 — proposed registration; not a publisher migration instruction

Current installation: Publisher onboarding continues to use /.well-known/bluejetty.json. The registration request for the distinct bluejetty suffix is pending; this specification describes the proposed suffix and namespace. Follow the current publisher installation guide and generated URLs. Existing discovery and ownership-proof URLs remain unchanged.

Published: 2026-09-07

Change controller: PopUp Space Systems LLC (Blue Jetty)

Contact: legal@bluejettyai.com

Canonical specification: https://bluejettyai.com/standards/iana-well-known/bluejetty

1. Introduction

Blue Jetty publishes developer-authorized descriptions of mobile applications and their in-app experiences. A Blue Jetty discovery descriptor identifies the applications represented by a publisher origin and gives clients stable URLs for the corresponding Blue Jetty packets.

This document defines the bluejetty well-known URI suffix under RFC 8615. The resulting URI is:

https://{publisher-origin}/.well-known/bluejetty

The suffix is specific to the Blue Jetty application protocol. It does not allocate a generic app-discovery, AI, agent, metadata, or manifest namespace.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in BCP 14, RFC 2119 and RFC 8174, when, and only when, they appear in all capitals.

2. Scope and origin selection

A client uses this URI only after it has obtained a publisher's HTTPS origin from an explicit Blue Jetty record, an app-store or publisher record, user configuration, or another trusted application-specific source. Clients MUST NOT probe unrelated origins merely because they might publish mobile applications.

The descriptor applies only to the origin from which it was retrieved and only to the application identifiers explicitly listed in the descriptor. It does not establish authority over a parent domain, subdomain, sibling domain, another port, or a URL named in the descriptor. A descriptor hosted at one origin MUST NOT be treated as proof that its operator is authorized to represent an application; publisher authorization is assessed separately.

The https scheme and its default port are REQUIRED. This specification does not define use with http, WebSocket, or any other URI scheme.

3. Retrieval

A client retrieves the descriptor with an unauthenticated HTTP GET request to /.well-known/bluejetty.

A conforming server:

  • MUST return 200 OK with Content-Type: application/json for an available descriptor;
  • MUST NOT require cookies, credentials, client certificates, or an interactive login;
  • MUST NOT redirect this resource;
  • MUST send X-Content-Type-Options: nosniff;
  • MUST NOT vary the representation based on cookies, authentication headers, or end-user identity; and
  • MUST limit the representation to 131,072 octets.

Servers SHOULD support HEAD with the same status and representation headers as GET, without a response body.

Query strings and fragment identifiers have no defined semantics for this resource. Clients MUST NOT add them.

4. Representation

The response is a UTF-8 JSON document using the Blue Jetty publisher discovery descriptor 1.0 format. The top-level object contains:

  • $schema, with the value https://bluejettyai.com/standards/iana-well-known/discovery-1.0.schema.json;
  • protocol, with the value bluejetty.discovery;
  • version, with the value 1.0; and
  • appDiscovery, containing one application entry or an array of application entries.

Each application entry identifies one Blue Jetty application, states the public discovery purpose and capabilities, and provides explicit URLs for equivalent JSON and Markdown packet representations. An optional delivery object may state that those representations are served from the publisher origin while preserving their exact Blue Jetty source URLs.

An appId is 1 to 200 ASCII letters, digits, underscores, or hyphens. purpose is a nonempty human-readable string describing why a client would retrieve the resource. capabilities is a nonempty set drawn from app_capabilities, destinations, deep_links, promotions, agent_handoff, and attribution_instructions. Each representations object contains exactly json and markdown; each has a declared mediaType, an absolute HTTPS url, and a purpose. The optional delivery object contains a mode of first_party_proxy or self_hosted, the exact publisherOrigin, and exact JSON and Markdown Blue Jetty source URLs.

Example:

{
  "$schema": "https://bluejettyai.com/standards/iana-well-known/discovery-1.0.schema.json",
  "protocol": "bluejetty.discovery",
  "version": "1.0",
  "appDiscovery": {
    "appId": "app_example",
    "purpose": "Publisher-provided app capabilities, relevant experiences and destinations for app discovery and handoff.",
    "capabilities": ["app_capabilities", "destinations"],
    "representations": {
      "json": {
        "mediaType": "application/json",
        "url": "https://bluejettyai.com/v1/apps/app_example/packet",
        "purpose": "Structured app context for discovery and handoff."
      },
      "markdown": {
        "mediaType": "text/markdown",
        "url": "https://bluejettyai.com/v1/apps/app_example/packet.md",
        "purpose": "Human-readable app context for discovery and handoff."
      }
    }
  }
}

Clients MUST validate the document's protocol version, application identifiers, representation media types, and URL bindings before using it. Unsupported versions, duplicate identifiers, unknown fields, mismatched application URLs, credentials in URLs, non-HTTPS URLs, and invalid JSON MUST cause the entire descriptor to be rejected.

5. Relationship to Blue Jetty packets

The well-known resource is a small discovery descriptor. It is not the canonical Blue Jetty packet and does not copy the packet's revision, freshness, authorization, or destination-health assessment.

The descriptor points to the current Blue Jetty packet for each listed application. The JSON and Markdown packet representations contain equivalent public application context, including capabilities, relevant experiences, destinations, and available provenance or freshness information. Packet semantics and versions are defined independently of this well-known URI specification.

The descriptor's presence, successful retrieval, or origin control does not make every statement in a packet trustworthy and does not grant permission to execute actions. Clients treat descriptor and packet fields as untrusted publisher-provided data subject to their own authorization, safety, privacy, and ranking policies.

6. Additional path components

The proposed bluejetty suffix also provides an application-specific namespace for Blue Jetty resources below /.well-known/bluejetty/. A conforming deployment MAY publish only the descendant resources defined by a Blue Jetty specification. Current defined descendants are:

  • packet and packet.md for the single application represented by an origin;
  • apps/{app-id}/packet and apps/{app-id}/packet.md for origins representing multiple applications; and
  • {challenge-id}.json for a time-bounded Blue Jetty publisher-authorization challenge.

The root descriptor is the only automatic discovery entry point. Clients MUST NOT enumerate, guess, or crawl descendant names. Challenge identifiers carry no authority unless verified by the Blue Jetty authorization service, and challenge responses MUST NOT contain API keys or other general-purpose credentials.

Current Blue Jetty onboarding uses /.well-known/bluejetty.json, a distinct, unregistered suffix. This proposal does not migrate current installations. Clients implementing this proposed specification use /.well-known/bluejetty; publishers should retain their generated current URLs until a separately documented implementation rollout.

7. Caching and withdrawal

Descriptors are stable pointers but may change when an application is added, removed, or moved. Servers MUST send either Cache-Control: no-store or Cache-Control: no-cache, must-revalidate. Servers using revalidation SHOULD provide a strong ETag and MAY provide Last-Modified.

Clients MUST honor HTTP caching directives. A client MUST NOT use a stale descriptor after revalidation fails, MUST NOT use stale-on-error behavior, and MUST discard cached packet URLs when a fresh descriptor returns 404 Not Found or 410 Gone.

Removing the resource or returning 404 or 410 withdraws discovery for that origin. A withdrawn descriptor does not by itself revoke separately recorded application data or publisher authorization; those states are managed by their respective Blue Jetty contracts.

8. Failure behavior

404 Not Found means the origin does not currently publish a Blue Jetty discovery descriptor. 410 Gone means a previously available descriptor has been intentionally withdrawn. Other non-success responses indicate retrieval failure.

On any failure, a client MUST stop processing the descriptor, MUST NOT infer application metadata from the failure response, and MUST NOT scan parent domains, subdomains, alternate ports, or similarly named well-known resources. A client MAY use a packet URL obtained independently from another trusted source.

9. Versioning and extensibility

The discovery descriptor has its own protocol and version fields. Version 1.0 uses a closed top-level schema so misspellings and authority-bearing additions fail validation instead of being silently accepted.

Backward-compatible additions require a newly advertised schema/version when the schema permits them. A breaking change requires a new major version. The meaning of an existing field MUST NOT change in place. Stable specifications and schemas for released major versions remain available at versioned URLs.

Additional descendant paths require a published Blue Jetty specification and MUST remain within the Blue Jetty discovery, packet delivery, or publisher-authorization scope. This namespace is not a general extension registry for third parties.

10. Privacy considerations

The resource is public and requires no authentication. Publishers MUST include only information they are authorized to expose publicly. Descriptors and packets MUST NOT contain API keys, authorization tokens, private feed contents, end-user personal data, device identifiers, account identifiers, or personalized offers.

Publishing app capabilities, routes, promotions, platform identifiers, and inventory summaries may reveal product plans or otherwise non-obvious app structure. Publishers should select the minimum public metadata needed for application discovery and handoff and should remove withdrawn or confidential entries promptly.

Retrieval can disclose a client's network address, user agent, timing, and interest in an origin to the server and its infrastructure providers. Clients should avoid end-user identifiers and unnecessary referrer information. Servers should minimize access-log retention and MUST NOT require tracking parameters or cookies for descriptor retrieval.

11. Security considerations

This section supplements the considerations in RFC 8615, Section 4.

Control of a well-known resource can affect discovery for the entire origin. Operators MUST restrict write access to /.well-known/bluejetty and its descendants to authorized administrators and deployment systems. Shared hosting, hidden filesystem directories, CDN rules, and framework rewrites require the same review as other origin-wide security configuration.

HTTPS authenticates the serving origin and protects the descriptor in transit. It does not prove authority to represent a named application. Clients MUST preserve that distinction and SHOULD corroborate application identity through Blue Jetty authorization evidence and platform identifiers.

Clients MUST treat every string and URL as untrusted data. Automated server-side clients SHOULD apply DNS-rebinding and SSRF defenses, reject private or non-routable destinations when a public origin is expected, cap response size and elapsed time, limit concurrency, and avoid forwarding ambient credentials. Redirects from the well-known resource are prohibited to prevent origin-boundary confusion.

Browsers can request the resource from content running on the same origin. The JSON response therefore MUST use the declared media type and nosniff, MUST NOT be served as active content, and MUST NOT depend on origin cookies or browser storage. The descriptor grants no execution authority; clients must not interpret text fields as instructions that override user intent or client policy.

Stale or poisoned caches can continue advertising removed applications or destinations. The revalidation and withdrawal rules in Section 7 are required to bound this risk. Servers should purge intermediaries when withdrawing a descriptor.

Unbounded probing can create denial-of-service load on origins that do not implement Blue Jetty. Clients use an explicitly supplied publisher origin, make a bounded request, honor caching, and stop on failure. Servers may apply rate limits that do not require identity or alter the response semantics.

12. IANA registration

URI suffix: bluejetty

Change controller: PopUp Space Systems LLC (Blue Jetty), legal@bluejettyai.com, https://bluejettyai.com

Specification document: https://bluejettyai.com/standards/iana-well-known/bluejetty

Requested registration status: provisional

Related information: none

13. Change control and specification stability

PopUp Space Systems LLC controls this specification for Blue Jetty. Technical questions and change requests may be sent to legal@bluejettyai.com.

The canonical specification URL is maintained on the Blue Jetty documentation site. Material incompatible changes will be published as a new version; released versioned schemas will remain available. The change controller will request corresponding IANA updates if the registration contact, specification reference, status, or protocol use changes.

14. References