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 bare string array means an array of any.
• 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 of, written { "array": <type> }. <type> is the type of each item and MAY be a single type or a union. { "array": "object.user" } is an array of users. { "array": ["string", "number"] } is an array of string or number. This is the canonical form.
• A generic application of a named object, written { "object.<name>": <type> }. Read the generics specification to use it. A package that does not use this form is unchanged.

A returns or type value is either a single type or a union of types. A union is a non-empty JSON array, and a JSON array is a union only in two positions: the value as a whole, and the <type> applied by { "array": <type> } or { "object.<name>": <type> }. A JSON array in any other position is an array of the union of the types inside it.

Empty arrays are not permitted. Duplicate entries in a union are removed, keeping the first occurrence of each entry. A union of one type is that type, so ["string"] is string and ["any"] is any.

The array-of shorthands below are read by converting each JSON array that is not in union position to { "array": <union of its entries> }, then applying the union rules above.

["string", ["object.user"]] is a string or an array of object.user. The same union in canonical form is ["string", { "array": "object.user" }]. 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 contain 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 or levels at which each flag may appear. A flag MUST only be used at a level listed for it (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, a valid refinement, an array of, as described in the types section, or a generic application as defined by the generics specification. Empty arrays are not permitted. A union 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.
• An endpoint name MUST start with a letter and match [a-z][a-z0-9-]*.
• Each argument name MUST start with a letter and match [a-z][a-z0-9_]*.
• Each attribute name MUST start with a letter and match [a-z][a-z0-9_]*.

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.