Package

Introduction

The Web Function Package specification simplifies endpoint interaction by standardizing their description and access. This defined structure ensures all endpoints are consistent, discoverable, and self-documented.

Package definition

A package is a JSON object that contains the following keys:

Endpoint definition

Each element in the endpoints array is an object that contains the following keys:

URL composition

The full URL of an endpoint is formed by joining the package's base_url and the endpoint's name with exactly one / separator:

• If base_url ends with a /, the name is appended directly.
• If base_url does not end with a /, a single / is inserted before the name.
• An endpoint name MUST NOT begin or end with a /.

For example, given a base_url of https://api.example.com (or, equivalently, https://api.example.com/) and an endpoint name of find-user-by, the full endpoint URL is https://api.example.com/find-user-by.

Event definition

Each element in the events array is an object that contains the following keys:

Argument definition

Each element in the arguments array is an object that contains the following keys:

Attribute definition

Each element in the attribute array is an object that contains the following keys:

Error definition

Each element in the error array is an object that contains the following keys:

Available flags

The Type column indicates the level at which each flag may appear. A flag MUST only be used at its designated level (package, endpoint, argument, or attribute) and MUST NOT appear at any other level.

Hints

A hint provides additional information about the data type of an endpoint, argument, or attribute. They are particularly useful for languages with strict typing or for providing more specific constraints than the base JSON types.

Validation requirements

The constraints expressed in the definition tables above—required versus optional keys, value types, allowed values, and flag scoping—are themselves normative and MUST be enforced.

In addition, each package MUST pass the following validations:

• The base URL MUST be valid as per RFC 3986.
• All specified types and flags MUST match defined constraints.

Security considerations

Several keys in a package—the docs field on the package, endpoints, events, arguments, attributes, and errors—contain Markdown authored by the API developer. Because a package may be fetched from a third party or generated dynamically, tooling that renders these docs fields MUST treat them as untrusted input. Renderers MUST neutralize embedded scripting and active content (for example, by sanitizing the generated HTML) to avoid cross-site scripting (XSS) and similar injection attacks.

Example

A simple example of a Web Function Package defining a single endpoint might look like this:

{
  "base_url": "https://api.example.com",
  "name": "ExamplePackage",
  "flags": [],
  "docs": "This package defines endpoints for Example API.",
  "errors": [],
  "endpoints": [
    {
      "name": "find-user-by",
      "returns": ["object"],
      "flags": [],
      "group": "users",
      "docs": "Retrieves user data.",
      "errors": [],
      "arguments": [
        {
          "name": "id",
          "type": "string",
          "choices": [],
          "flags": ["required"],
          "docs": "Identifier of the user."
        }
      ]
    }
  ]
}

Retrieval

A package can reach a client in more than one way, but only one of them is governed by this specification.

• Invocation response (covered). A Web Function Package MAY be returned as the response body of a Web Function Endpoint invocation, that is, an HTTP POST as described in the endpoint specification. This is the only retrieval method defined by this specification. It enables a dynamic and recursive discovery mechanism where endpoints return packages as part of their operation, supporting complex scenarios where packages are interdependent or where the structure of available APIs can change.

• Side-loaded (out of scope). A package MAY also be obtained out of band, for example distributed as a static file read from the filesystem, or fetched with a plain HTTP GET. Such a side-loaded package MAY be static or dynamically generated by a web application so its contents adapt to the request or to application state. These mechanisms are common and perfectly valid, but they are not part of this specification: how a side-loaded package is located, transported, or cached is left entirely to the implementation.