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:

Types

Everywhere a type is expected—an endpoint's returns, or an argument's or attribute's type—it is expressed using the following grammar.

A type is one of:

• A base JSON type, written as a bare string: object, array, string, number, boolean, or null.
• The special any type, which represents any base JSON type. any MUST NOT be refined.
• A refined type, written as a base type and a refinement joined by a dot, for example number.u32, string.email, or object.user. See the refinements section for the complete list. An object.<name> refinement references a definition in the package's objects array.
• An array type, written as a JSON array whose entries are the types that the array's items may take (a union). This is fully recursive: an array's items may themselves be array types. An array type MUST NOT be empty; the bare string array and ["any"] are equivalent and denote an array of any.

A returns or type value is either a single type or a union of types written as a non-empty JSON array. When it is an array, the outermost array is the union itself, so an entry that is an array is an array type. Empty arrays are not permitted anywhere: use the bare any (equivalently ["any"]) to match a value of any type, and the bare array (equivalently ["array"]) to match an array of any. A nested array appearing as an entry is an array type, as described above.

For example, ["string", ["object.user"]] represents a value that is either a string or an array of object.user, while the bare "object.user" is a single user object and "any" matches any value.

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:

Object definition

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

An object.<name> reference appears in one of two contexts, which determines which set of definitions applies:

• Argument context — the object is referenced as an argument's type. The object's arguments describe its members.
• Attribute context — the object is referenced as an endpoint's returns or as an attribute's type. The object's attributes describe its members.

The context propagates recursively: when an argument's or attribute's type references another object, that nested object is interpreted in the same context as the definition that references it. Because an object MAY be referenced in both contexts within the same package, it MAY define both arguments and attributes; each set is used only in its matching context.

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.

Refinements

A refinement narrows a base JSON type, providing more specific constraints than the base JSON types alone. Refinements are particularly useful for languages with strict typing. A refined type is written by joining the base type and the refinement with a dot, for example number.u32 or string.email.

The any type MUST NOT be refined. In addition to the refinements listed below, the object type may be refined with the name of a definition in the package's objects array (object.<name>).

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.
• Every type in a returns or type value MUST be a valid base type, any, or a valid refinement. Arrays MUST NOT be empty at any depth; a union and every array type MUST contain at least one entry.
• The any type MUST NOT be refined.
• Each object.<name> refinement MUST resolve to an entry in the package's objects array.
• An object referenced in an argument context MUST define an arguments array; an object referenced in an attribute context MUST define an attributes array.
• Object names MUST be unique within the package.

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": [],
  "objects": [
    {
      "name": "user",
      "attributes": [
        {
          "name": "id",
          "type": "string.uuid"
        },
        {
          "name": "email",
          "type": "string.email"
        }
      ]
    }
  ],
  "endpoints": [
    {
      "name": "find-user-by",
      "returns": "object.user",
      "flags": [],
      "group": "users",
      "docs": "Retrieves user data.",
      "errors": [],
      "arguments": [
        {
          "name": "id",
          "type": "string.uuid",
          "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.