PortableWeb Format: Container and Manifest Specification

1.1. Design Goals

The PortableWeb format is designed to:¶

• Be openable by any compatible viewer on any platform, entirely offline.¶

• Behave like a document: saveable, copyable, shareable, and archivable.¶

• Support any interactive content built on standard web technologies.¶

• Operate without a Web origin and without being confined to a web browser.¶

• Declare capabilities and permissions upfront in a structured manifest.¶

• Provide a stable, versioned format with long-term backwards compatibility.¶

• Be identifiable without unpacking (via magic bytes and a mimetype entry).¶

• Remain simple enough that a conforming implementation can be built quickly.¶

1.2. Scope of This Document

This document defines:¶

1. The container format: how a .pweb file is structured as a ZIP archive (Section 3).¶

2. The manifest schema: the manifest.json file that every bundle must contain (Section 4).¶

3. Security considerations for implementations (Section 6).¶

4. IANA considerations for the application/vnd.portableweb+zip media type (Section 7).¶

The following are out of scope for this document and will be addressed in companion specifications:¶

• The runtime sandbox and security model (SANDBOX).¶

• The frozen subset of supported web platform features per spec version (RUNTIME-PROFILE).¶

• Cryptographic signing of bundles (SIGNING).¶

• Storage, permissions, and user data isolation (STORAGE).¶

• Inter-bundle communication via local channels such as Bluetooth and Wi-Fi Direct (COMMS).¶

3.1. File Extension and Media Type

A PortableWeb bundle uses the following identifiers:¶

• File extension: .pweb¶

• Media type: application/vnd.portableweb+zip¶

• Magic bytes: 50 4B 03 04 (PK\003\004) — the standard ZIP local file header signature.¶

A viewer MUST accept files with the .pweb extension or the application/vnd.portableweb+zip media type. A viewer SHOULD also identify bundles by inspecting the mimetype entry described in Section 3.3.¶

3.2. Outer Container

A bundle MUST be a valid ZIP archive. The ISO/IEC 21320-1 Document Container File profile [ISO21320] is RECOMMENDED. Specifically:¶

• The archive MUST NOT be encrypted.¶

• The archive MUST NOT be split across multiple files.¶

• File and directory names inside the archive MUST use forward slashes (/) as path separators, encoded in UTF-8.¶

• The archive SHOULD NOT contain absolute paths or .. path components.¶

3.3. The mimetype Entry

A bundle MUST contain a file named mimetype at the archive root with the following properties:¶

• Contents: the ASCII string application/vnd.portableweb+zip with no trailing newline or whitespace.¶

• Position: the first entry in the ZIP archive.¶

• Compression: STORED (method 0, uncompressed).¶

• No extra fields in the local file header.¶

This convention, borrowed from EPUB [EPUB3], allows a tool to identify a PortableWeb bundle by reading the first approximately 80 bytes of the file without unpacking the archive.¶

3.4. The manifest.json Entry

A bundle MUST contain a file named manifest.json at the archive root, encoded as UTF-8 JSON [RFC8259] without a byte order mark. The manifest schema is defined in Section 4. At minimum, the manifest declares:¶

• The spec version the bundle targets.¶

• A unique bundle identifier.¶

• The bundle version.¶

• A human-readable title.¶

• The path to the entry HTML file.¶

• Any declared permissions.¶

3.5. The Entry File

A bundle MUST contain the file referenced by the manifest's entry field. The entry file MUST have a .html or .htm extension and MUST be valid HTML5. The entry file is loaded by the viewer in a sandboxed context. All other files in the bundle are addressable from the entry file using relative paths.¶

3.6. Recommended File Layout

The following layout is RECOMMENDED but not required. Bundles MAY use any layout consistent with this section.¶

example.pweb (zip)
├── mimetype                  (required, first, uncompressed)
├── manifest.json             (required, at root)
├── index.html                (required, entry file)
├── assets/                   (recommended: images, fonts, icons)
├── scripts/                  (recommended: JavaScript files)
├── styles/                   (recommended: CSS files)
├── media/                    (recommended: audio and video)
└── data/                     (recommended: JSON and static data)

3.7. Reserved Paths

The following paths at the archive root are reserved by this specification. Bundles SHOULD NOT create files at these paths unless following an explicit PortableWeb sub-specification:¶

• mimetype¶

• manifest.json¶

• META-INF/ (reserved for signature manifests and integrity data)¶

• .well-known/ (reserved for future use)¶

3.8. Bundle Identification

A viewer SHOULD identify a file as a PortableWeb bundle if any of the following conditions are true:¶

1. The file extension is .pweb.¶

2. The file's declared media type is application/vnd.portableweb+zip.¶

3. The first ZIP entry is a STORED file named mimetype containing exactly application/vnd.portableweb+zip.¶

A viewer SHOULD reject any file claiming to be a PortableWeb bundle that fails to validate against this section.¶

3.9. Versioning

The container format is versioned independently from companion specifications. This document describes container version 0.1.¶

Future container versions MUST remain backwards compatible. A bundle declaring spec_version: "1.0" in its manifest MUST remain openable by any future viewer that claims support for v1.0 bundles. New features are added in new spec versions; existing features are not removed. This guarantee is the foundation of the PortableWeb archival promise.¶

4.1. Overview

Every PortableWeb bundle contains a manifest.json file at its archive root. The manifest is the bundle's structured metadata: it identifies the bundle, declares its entry point, specifies requested permissions, and carries rights and authorship information.¶

4.2. Format

The manifest MUST be a valid JSON document [RFC8259] encoded as UTF-8 without a byte order mark. The top-level value MUST be a JSON object.¶

4.3. Required Fields

The following fields MUST be present in every conforming manifest:¶

4.4. Recommended Fields

The following fields are RECOMMENDED:¶

4.5. Permissions

Permissions are declared upfront in the manifest and are not requested at runtime. Any permission not declared is denied by default. Viewers SHOULD present declared permissions to the user when a bundle is first opened.¶

Future versions of this specification MAY define additional permission keys. Viewers MUST ignore unknown permission keys when the bundle targets a spec version the viewer supports.¶

4.6. The rights Object

4.7. The viewport Object

These are hints, not requirements. Viewers MAY override them based on the user's environment or platform conventions.¶

4.8. Example: Minimal Valid Manifest

{
  "spec_version": "0.1",
  "id": "org.example.minimal",
  "version": "1.0.0",
  "title": "Minimal Example",
  "entry": "index.html"
}

4.9. Example: Full Manifest

{
  "spec_version": "0.1",
  "id": "org.example.solar-system",
  "version": "1.2.0",
  "title": "Interactive Solar System",
  "description": "Explore planet orbits and relative scales of our solar system.",
  "content_type": "simulation",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "url": "https://janedoe.example.com"
  },
  "created": "2026-05-24T00:00:00Z",
  "icon": "assets/icon.svg",
  "entry": "index.html",
  "permissions": {
    "network": false,
    "camera": false,
    "microphone": false,
    "storage": "isolated",
    "fullscreen": true,
    "peers": false
  },
  "rights": {
    "copyright": "© 2026 Jane Doe",
    "license": "CC-BY-4.0",
    "license_url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "viewport": {
    "preferred_width": 1280,
    "preferred_height": 800,
    "resizable": true,
    "min_width": 800,
    "min_height": 600
  }
}

4.10. Validation

Viewers and tools SHOULD validate manifests against the schema before opening a bundle. A formal JSON Schema document for this manifest will be published at https://portableweb.org/spec/manifest.schema.json.¶

6.1. Sandboxed Execution

PortableWeb content is intended to be processed by a viewer, not executed as native operating-system code. Viewers that render active content SHOULD do so in a sandboxed execution environment with no ambient access to the host application, local files, device APIs, credentials, cookies, or other user data except where the user has explicitly granted access. Viewers SHOULD:¶

• Isolate storage per bundle.¶

• Restrict or mediate network access according to user or application policy.¶

• Prevent script access to the viewer application's privileged interface.¶

• Apply the security model of the underlying web rendering engine.¶

• Prevent active content from escaping the sandbox through navigation, popups, downloads, same-origin confusion, or unrestricted access to host-provided APIs.¶

6.2. Permission Model

A PortableWeb manifest declares the capabilities requested by the bundle. These declarations are inputs to the viewer's security policy and are not security guarantees by themselves. Viewers SHOULD apply a deny-by-default policy and SHOULD allow only the capabilities explicitly permitted by both the manifest and the viewer or user policy. Viewers MAY ignore or further restrict manifest-declared capabilities.¶

6.3. Confidentiality and Integrity

The media type itself provides no confidentiality, integrity, authentication, authorization, or replay protection. Where confidentiality or integrity is required, it SHOULD be provided externally, for example by HTTPS or TLS during transport, operating-system file protections, digital signatures, or checksums. Viewers SHOULD make trust decisions based on the source and integrity of the package before enabling higher-risk capabilities.¶

Cryptographic signing of PortableWeb bundles is defined in the companion SIGNING specification.¶

6.4. ZIP Container Security

PortableWeb files are ZIP-based binary containers. The security considerations for ZIP containers and compressed content apply. Implementations SHOULD protect against:¶

• Decompression bombs and excessive memory or disk usage.¶

• Deeply nested archives.¶

• Duplicate or ambiguous filenames.¶

• Absolute paths and path traversal sequences such as ../.¶

• Symbolic links and platform-specific path handling issues.¶

• Filename normalization conflicts.¶

• Mismatches between ZIP metadata and actual content.¶

Implementations SHOULD impose reasonable limits on total uncompressed size, file count, nesting depth, path length, and individual resource size before extraction or rendering. Implementations SHOULD NOT extract files outside an application-controlled storage area.¶

6.5. External Resources

PortableWeb packages may contain internal links between packaged resources and may optionally reference external resources when the network permission is granted. Viewers SHOULD clearly distinguish packaged local resources from external resources and SHOULD mediate or block external navigation and network requests according to user or application policy.¶

7.1. Media Type Registration

This document registers the following media type:¶

Type name:

application¶

Subtype name:

vnd.portableweb+zip¶

Required parameters:

None.¶

Optional parameters:

None.¶

Encoding considerations:

Binary.¶

Security considerations:

See Section 6 of this document.¶

Interoperability considerations:

See Section 5 of this document.¶

Published specification:

This document.¶

Applications that use this media type:

PortableWeb viewer applications, authoring tools, packaging tools, validation tools, document-management systems, file managers, web servers, content-distribution systems, and AI content generation tools that create, distribute, inspect, validate, store, or render PortableWeb packages.¶

Fragment identifier considerations:

Fragment identifier semantics are not defined by this registration for the PortableWeb container as a whole. Fragment identifiers within packaged resources are interpreted according to the rules of the individual resource media type. If a future version of this specification defines PortableWeb-specific fragment identifier syntax, this registration will be updated.¶

Additional information:

Magic number(s): 50 4B 03 04 (PK\003\004)¶

File extension(s): .pweb¶

Macintosh file type code: N/A¶

Object Identifiers: N/A¶

Person to contact for further information:

Omprakash Selvaraj, maintainer@portableweb.org¶

Intended usage:

COMMON¶

Restrictions on usage:

None.¶

Author:

Omprakash Selvaraj¶

Change controller:

Omprakash Selvaraj¶

8.1. Normative References

[ISO21320]

"ISO/IEC 21320-1: Document Container File — Part 1: Core", 2015, <https://www.iso.org/standard/60101.html>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]

Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", December 2017.

8.2. Informative References

[EPUB3]

"EPUB 3.3", 2023, <https://www.w3.org/TR/epub-33/>.

[RFC6838]

Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", January 2013.

[SEMVER]

"Semantic Versioning 2.0.0", 2013, <https://semver.org/>.

[SPDX]

"SPDX License List", n.d., <https://spdx.org/licenses/>.

[WAM]

"Web Application Manifest", 2023, <https://www.w3.org/TR/appmanifest/>.

[WASM]

"WebAssembly Core Specification", 2022, <https://www.w3.org/TR/wasm-core-2/>.

[ZIP]

"APPNOTE.TXT — .ZIP File Format Specification", n.d., <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>.