IA² HTML Agent Resource Envelope 0.1

The IA² HTML Agent Resource Envelope (HARE) is a single-file HTML envelope for exchanging a graph of inspectable web resources between people, applications, and agents. The envelope is an ordinary browser-openable document. Its canonical manifest is a named RDF graph carried by HTML/RDF statement elements. Semantic HTML can be carried directly as inert DOM, while exact bytes remain available as an optional committed representation. An optional runtime can enhance the same file into an offline viewer without becoming the authority for its contents.

Conceptual model

Envelope: The HTML document and its source bytes.
Manifest: One named RDF graph extracted from the envelope.
Resource: An identified conceptual entity in the bundle.
Representation: A particular semantic or byte realization of a resource.
Carrier: The HTML element containing a representation.
Runtime: Optional code that presents the graph and its representations.

Graph identity and logical paths

The primary abstraction is a graph. Resource IRIs carry identity; RDF predicates carry relationships and provenance. Logical paths are secondary aliases used for familiar web-relative lookup. Moving a representation to another logical path does not create a new resource unless the producer intentionally assigns a new identity. The envelope's virtual base and these paths assign browser-like navigation URLs without replacing RDF identity.

A directory boundary has no semantic meaning by itself. A producer that needs collection, order, membership, or containment MUST express that meaning as RDF.

Resource and representation

A resource is the thing described. A representation is a particular realization of it. A DOM representation carries parsed semantic HTML. A byte representation carries an exact sequence of octets. Media type, path, carrier, and any byte commitment are properties of the representation, not the abstract resource. A resource MAY have more than one representation.

Canonical retrieval locations

The envelope's source document IRI is established according to the HTML/RDF Core Model. When the envelope is published at a stable retrievable location, its producer SHOULD include one usable HTML link element whose rel token set contains canonical. If such a link is present, there MUST be exactly one and its href MUST resolve to a fragmentless absolute IRI. When no stable canonical location is available, the retrieval IRI remains the source document IRI.

If a bundled HTML representation is also published at a stable retrievable location, its producer SHOULD include exactly one usable canonical link in that representation's own head. This allows the representation to retain the same semantic source IRI when it is retrieved directly or extracted from the envelope.

<head>
  <link rel="canonical" href="https://example.org/reports/atlas">
</head>

If a canonical link is included in a byte representation, a producer MUST insert or update it before computing that representation's byte length and integrity value because the link is part of the represented bytes. A consumer MUST NOT treat a canonical link as evidence of availability, integrity, authority, or permission, and MUST NOT dereference it merely to process the envelope.

Non-HTML representations cannot carry an HTML canonical link. A producer MAY describe their retrieval locations in the manifest using an appropriate established or application vocabulary. HARE 0.1 does not define a general remote-location property.

Relations and derived artifacts

Ordinary relationships are ordinary RDF statements. The format does not define a generic edge record. Producers SHOULD use established vocabularies where their semantics fit. In particular, prov:wasDerivedFrom, prov:wasQuotedFrom, and prov:wasGeneratedBy can describe derivation without introducing a packaging-specific model [[PROV-O]].

A derived artifact is a resource with one or more explicit provenance relationships. It is not a separate container primitive.

Canonical manifest

The canonical manifest is the named RDF graph identified by the envelope's manifestGraph statement. It is not a JSON or JSON-LD data block.

The manifest SHOULD be visibly grouped in a section whose id is manifest. The section SHOULD declare the named graph:

<section id="manifest" rdf-graph="#manifest">

HTML/RDF does not inherit graph state. Every manifest statement carrier MUST therefore state rdf-graph="#manifest" explicitly. This repetition keeps each statement locally complete.

Manifest discovery algorithm

A consumer MUST perform these steps without executing code:

Parse the source as an HTML document.
Extract its RDF dataset according to the declared HTML/RDF version.
Find subjects whose rdf:type is Envelope.
Fail if there is not exactly one such subject.
Require a dcterms:conformsTo statement naming the supported HARE specification profile.
Require exactly one supported artifact profile.
Read its manifestGraph object and select that named graph.
Fail if the named graph is absent from the extracted dataset.
Read and validate its virtualBase.

HARE vocabulary

The vocabulary namespace is https://ia2.dev/spec/resource-envelope#. Terms not defined here remain application vocabulary. Consumers MUST preserve unknown statements and MUST NOT dereference the namespace to process a bundle.

Classes

Envelope: The HTML artifact as a self-contained resource bundle.
Representation: A semantic or byte realization of a resource.
DOMRepresentation: A semantic HTML fragment carried by a template.
ByteRepresentation: An exact sequence of octets carried as base64.
ViewerRuntime: Executable enhancement code declared by a self-viewing envelope.

Properties

Term	Range	Meaning
`manifestGraph`	IRI	Canonical manifest graph name.
`virtualBase`	IRI	Non-retrievable root URL of the envelope's virtual document space.
`representation`	Representation	Representation of a resource.
`carrier`	IRI	HTML element containing the representation.
`byteLength`	non-negative integer	Decoded length of a byte representation.
`runtime`	ViewerRuntime	Declared viewer runtime.

Reused vocabulary

HARE defines packaging mechanics only. Membership, conformance, identifiers, media types, and SRI digests use established terms [[DCMI-TERMS]] [[VC-VOCABULARY]]. The following meanings are normative within a HARE manifest:

Term	HARE use
`dcterms:conformsTo`	Names the HARE version and artifact profile.
`dcterms:hasPart`	Relates the envelope to each included conceptual resource.
`dcterms:identifier`	Optionally gives a representation a logical path, unique within the envelope.
`dc:format`	Gives a representation its IANA media type string.
`cred:digestSRI`	Gives a byte representation its SHA-256 SRI digest.

HARE deliberately retains byteLength. PREMIS hasSize is a useful archival mapping, but importing its File or Bitstream domain would impose a preservation-specific object model [[PREMIS-OWL]]. On a byte representation, HARE requires the exact number of decoded octets.

Specification and artifact profiles

HARE-0.1 identifies this version of the format. DeclarativeProfile and SelfViewingProfile identify the two artifact profiles. They are RDF resources rather than version or policy string literals.

Validation shapes

The minimum structural schema is a SHACL graph carried by this specification as HTML/RDF. It is not a second serialization of the manifest. Validators MUST apply these shapes to the canonical manifest graph and MUST additionally perform the byte and uniqueness checks defined by the processing rules.

Target	Required properties	Additional constraint
`Envelope`	`dcterms:conformsTo`, `manifestGraph`, `virtualBase`, one or more `dcterms:hasPart`	Conforms to HARE 0.1 and exactly one artifact profile
`Representation`	`dc:format`, `carrier`; optional `dcterms:identifier`	Exactly one representation kind
`DOMRepresentation`	Representation properties and `dcterms:identifier`	The carrier is a `template`; the logical path assigns its virtual URL
`ByteRepresentation`	Representation properties, `byteLength`, `cred:digestSRI`	The carrier is a base64 data block

Representation model

Each representation MUST have exactly one representation-kind type and MUST have exactly one:

dc:format, containing its media type;
carrier.

A representation MAY have one dcterms:identifier used as a logical path. A representation without a path remains addressable by its RDF IRI and MUST NOT be treated as a virtual file.

DOM representations

A DOM representation MUST be typed as DOMRepresentation, MUST use media type text/html, and MUST identify a template element with a unique id as its carrier. It MUST have a logical path, which assigns it a URL in the envelope's virtual document space. Its semantic content is the template's parsed document fragment. It is not defined by an original serialization.

<template id="brief-content">
  <article>
    <h1>Release brief</h1>
    <p>Approve the Atlas migration.</p>
  </article>
</template>

Consumers MUST inspect or clone the fragment without executing its scripts. Serializing or downloading the fragment produces a derived artifact; it does not recover original source bytes. A producer that needs an exact downloadable HTML file SHOULD add a separate byte representation for the same resource.

Byte representations

A byte representation MUST be typed as ByteRepresentation and MUST have exactly one byteLength and cred:digestSRI. Its carrier MUST be a script data block with a unique id, a type of application/octet-stream, and a data-encoding value of base64.

<script
  id="brief-bytes"
  type="application/octet-stream"
  data-encoding="base64"
>IyBSZWxlYXNlIGJyaWVmCg==</script>

Base64 preserves arbitrary bytes independently of HTML parsing, entity decoding, and newline normalization [[RFC4648]]. Text SHOULD use a semantic carrier when source-byte preservation is unnecessary.

Carrier processing

The carrier object MUST resolve to the envelope source IRI plus one fragment. The consumer MUST locate the element with the decoded fragment identifier and then dispatch according to representation kind.

To process a DOM representation, a consumer MUST:

Require the carrier to be a template.
Return its parsed document fragment without executing content.

To process a byte representation, a consumer MUST:

Require the carrier to have the required element name, type, and encoding attributes.
Read its DOM text content.
Remove ASCII whitespace.
Decode strict padded base64.
Compare the decoded length with byteLength.
Compute SHA-256 over the decoded bytes.
Compare the result with cred:digestSRI.
Return bytes only if every check succeeds.

Byte commitments

Byte-representation integrity values MUST use the Subresource Integrity form sha256-<base64-digest>. The digest is computed over decoded representation bytes, not base64 source text [[SRI]]. The RDF literal MUST have datatype https://www.w3.org/2018/credentials#sriString. HARE 0.1 does not define a canonical serialization or digest for DOM representations.

Virtual document URLs and logical paths

Each envelope MUST declare one virtualBase. It assigns the host envelope document a virtual URL and establishes the base for every path-addressed representation. The value MUST be a credential-free HTTPS URL under the reserved .invalid top-level domain, with path / and no query or fragment. It is a routing identifier only and MUST NOT be dereferenced. The reserved top-level domain prevents collision with a retrievable Web origin [[RFC2606]]. Producers SHOULD choose a stable, collision-resistant host label for the envelope. Consumers MUST scope virtual URLs to their declaring envelope and MUST NOT use them for cross-envelope identity.

<a hidden href="https://northstar.hare.invalid/"
  rdf-subject=""
  rdf-predicate="https://ia2.dev/spec/resource-envelope#virtualBase"
  rdf-graph="#manifest"></a>

The virtual URL of the host document is the virtualBase itself. The virtual URL of a representation with a logical path is the result of resolving that path against the base. For example, /pages/summary.html becomes https://northstar.hare.invalid/pages/summary.html. Virtual URLs provide browser-like navigation addresses; RDF IRIs remain the identities of the envelope, resources, and representations.

A logical path MUST:

start with /;
not be /, which is reserved for the host document;
contain URI path segments separated by /;
contain no query or fragment;
contain no empty, ., or .. segments;
use uppercase hexadecimal digits in percent-encoding;
not encode slash, backslash, dot segments, or NUL; and
be unique within the envelope using case-sensitive comparison.

A consumer MUST resolve links in a DOM representation against that representation's virtual URL. A result matching another declared virtual URL navigates to that representation. A result matching the virtualBase, including /, navigates to the host document. URL fragments identify elements within the selected document. A result outside the declared virtual origin is external and MUST require a deliberate user navigation; it MUST NOT be fetched merely to render the envelope.

<template id="summary-content">
  <article>
    <h1 id="result">Review result</h1>
    <a href="../data/status.json">Structured status</a>
    <a href="/">Envelope document</a>
  </article>
</template>

A representation without a logical path has no virtual URL and cannot be the target or base of a relative bundle link. Byte representations MAY omit a logical path. DOM representations MUST supply one so that every viewable document, including the host, has an unambiguous virtual URL.

Optional runtime model

A viewer runtime MAY index resources, search text, resolve links, create Blob URLs, render previews, and maintain navigation state. It MUST derive its inventory from the HTML/RDF manifest, MUST keep DOM carriers inert, and MUST verify byte representations before rendering or downloading them.

A viewer SHOULD render:

DOM representations in a sandboxed iframe without scripts;
HTML byte representations in a sandboxed iframe after verification;
Markdown as a derived safe DOM view that does not interpret raw HTML;
JSON as a tree and escaped source;
images through verified Blob URLs;
PDF through a sandboxed browser surface or explicit save action; and
unknown binaries as metadata with an explicit save action.

Runtime code required for an offline self-viewing envelope MUST be inline or embedded. A conforming self-contained envelope MUST NOT depend on CDN-hosted code, styles, fonts, contexts, or schemas.

To present a DOM representation as a document, a viewer MUST derive a browsing document from the template fragment, set its base URL to the representation's virtual URL, keep representation scripts disabled, prevent automatic network loads, and route activated links according to virtual document URL processing. The derived browsing document is presentation state, not a byte representation of the resource.

A viewer MUST prevent an authored navigation URL from being followed directly by the derived browsing context. It SHOULD make anchors inert in the derived document before presentation, preserve each authored reference as routing data, and intercept activation in the capture phase. This requirement applies before and after the viewer's routing handler is installed. The viewer then resolves the preserved reference through the envelope's virtual URL space. It MUST NOT navigate the frame to a virtual .invalid URL or use the network as a fallback. The template carrier itself remains unchanged.

Host Content Security Policy compatibility

A Content Security Policy on the envelope document and a policy in a derived browsing document are cumulative. A derived document's policy can further restrict its content, but it cannot loosen the envelope's policy. In particular, a srcdoc document inherits the relevant policy container from its embedder. Producers and viewer authors MUST NOT assume that an inner policy can restore a frame, stylesheet, image, media resource, or font blocked by the host policy [[CSP3]].

A Self-Viewing Envelope that declares a host Content Security Policy MUST permit the mechanisms used by its declared runtime. A Declarative Envelope is not required to permit an in-document viewer. When a producer intends a declarative envelope to remain compatible with consumer-provided browser viewers, its host policy SHOULD permit the local frame and passive-resource schemes used by the intended rendering strategy while continuing to deny network and executable destinations.

The following policy is a baseline for a scriptless envelope whose consumer may use srcdoc frames and materialized blob: or existing data: passive resources. It is an example, not a universal policy:

<meta http-equiv="Content-Security-Policy" content="
  default-src 'none';
  style-src 'unsafe-inline' blob: data:;
  img-src blob: data:;
  media-src blob: data:;
  font-src blob: data:;
  frame-src 'self' blob: about:;
  object-src 'none';
  worker-src 'none'
">

The about: frame source permits about:srcdoc; blob: permits verified local byte views; and the passive destination directives permit only local materialized content. A self-viewing profile MAY add the narrowest script-src needed for its declared runtime. It MUST NOT grant script execution to representation content. A consumer-provided viewer MUST report a host-policy block and MUST NOT weaken, replace, or bypass the producer's policy by fetching the resource from the network.

Developer tools, automation frameworks, or unrelated extensions may attempt to evaluate their own instrumentation inside a scriptless representation frame. A user agent can report that attempt as blocked script execution even when the derived document contains no script. Viewers and validators SHOULD distinguish tooling injection from representation content by inspecting the derived document and the initiator. They MUST NOT add allow-scripts merely to suppress this diagnostic.

Verified subresource materialization

A viewer MAY materialize passive subresources referenced by a DOM representation, a rendered Markdown byte representation, or an explicit binding from the host document. Materialization turns a virtual URL into a viewer-local URL, such as a Blob URL, only after the referenced byte representation has been verified. It does not change the carrier, representation, manifest graph, or virtual URL and MUST NOT be treated as a new representation.

For each subresource reference, a materializing viewer MUST:

resolve the reference against the containing representation's virtual URL, or against virtualBase for a host-document binding;
require the result, excluding its fragment, to match the virtual URL of a declared byte representation;
verify that representation's base64, decoded length, and digest before use;
require its declared media type to be suitable for the fetch destination;
create a viewer-local URL for the verified bytes and preserve any URL fragment; and
rewrite only the derived browsing document, rendered Markdown view, derived stylesheet, or runtime fetch attribute corresponding to an explicit inert host-document binding.

A materializing viewer SHOULD support passive image, audio, video, track, SVG image, SVG use, stylesheet, srcset, inline style, and CSS url() references. It SHOULD recursively materialize CSS @import and url() dependencies, cache verification and local URLs by representation, detect import cycles, and revoke temporary URLs when the derived view is discarded.

A viewer MUST NOT automatically fetch an unmatched or external subresource reference. It MUST NOT materialize scripts, workers, nested browsing contexts, plugins, or executable destinations, even when a byte representation exists. A DOM representation is a navigable document, not a passive subresource, and MUST NOT be substituted into an image, stylesheet, media, or similar fetch destination. Existing data: references MAY remain inline; authored blob: references have no portable meaning across consumers. Blocked, missing, incompatible, cyclic, or unverifiable references MUST remain inert and SHOULD be reported to the user.

A host document MUST NOT put a non-retrievable virtual URL directly in src, because the browser can attempt that request before a viewer runs. An authored host MAY instead use data-hare-src on an element with a passive src fetch destination. A supporting viewer resolves that value against virtualBase, applies the same representation, media-type, length, and digest checks, and writes only the resulting viewer-local URL to src. It MUST retain data-hare-src as the inspectable declarative reference. Consumers that do not support this optional binding leave it inert.

A Markdown renderer MAY recognize image destinations in verified Markdown bytes. It MUST resolve each destination against the Markdown representation's virtual URL and apply the same declared representation, media-type, length, and digest checks before placing a viewer-local URL in the rendered image. It MUST preserve the authored reference in the source bytes, MUST NOT fetch an unmatched destination, and MUST NOT enable raw HTML or script execution merely to render Markdown.

A Markdown renderer SHOULD support the conventional portable surface of headings, paragraphs, emphasis, links, images, block quotations, ordered and unordered lists, code, and tables. HARE does not define a new Markdown dialect and version 0.1 does not require CommonMark conformance. A renderer MUST construct or sanitize its derived view so raw HTML remains inert. Markdown links MUST use the same virtual URL routing rules as links in DOM representations; a consumer MUST NOT turn an unresolved virtual link into a network request.

<template id="summary-content">
  <link rel="stylesheet" href="../styles/report.css">
  <article>
    <img src="../images/verified.svg" alt="Verified">
  </article>
</template>

<figure>
  <img data-hare-src="/images/verified.svg" alt="Verified bundle">
  <figcaption>Image carried by this envelope.</figcaption>
</figure>

In this example, the template remains directly inspectable. A materializing viewer resolves both relative URLs in the virtual document space, verifies the corresponding byte representations, and rewrites a derived document to local URLs. It never edits the template carrier. The second example opts the host document into the same verified lookup without placing the virtual URL in a browser-fetching attribute.

A consumer, including a browser extension, MAY provide its own viewer for an envelope that contains no runtime. A consumer-provided viewer does not change the envelope's declared artifact profile and MUST NOT execute code found in bundled representations by default.

Profile	Requirements
Declarative Envelope	No executable scripts, event-handler attributes, `javascript:` URLs, automatic remote fetches, or active embedded documents.
Self-Viewing Envelope	Declares every viewer runtime, remains meaningful without it, and does not execute scripts found inside bundled representations by default.

Format	Strength	Why it is not this format
ZIP plus manifest	General packaging and compression	Requires extraction and leaves semantics to another format.
Web Bundles	Collections of HTTP exchanges	Binary and centered on delivery rather than inspectable agent handoff.
PortableWeb	Packaged web applications	ZIP and JSON manifest with a specialized viewer [[PORTABLEWEB]].
WARC and WACZ	Capture, indexing, and replay	Preserves web observations rather than an authored resource graph [[WACZ]].
EPUB	HTML-centered publications	ZIP container and publication-specific reading model [[EPUB-33]].
MHTML	One page and its dependencies	MIME aggregate without an agent-oriented graph manifest [[RFC2557]].
Plain JSON	Simple API interchange	Poor browser document and duplicates semantics outside visible HTML.

Examples

The following fragments are non-normative. They use full IRI references because HTML/RDF does not define prefix expansion.

Envelope and manifest declaration

<section id="manifest">
  <a hidden href="https://ia2.dev/spec/resource-envelope#Envelope"
    rdf-subject=""
    rdf-predicate="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
    rdf-graph="#manifest"></a>
  <a hidden href="https://ia2.dev/spec/resource-envelope#HARE-0.1"
    rdf-subject=""
    rdf-predicate="http://purl.org/dc/terms/conformsTo"
    rdf-graph="#manifest"></a>
  <a hidden href="https://ia2.dev/spec/resource-envelope#DeclarativeProfile"
    rdf-subject=""
    rdf-predicate="http://purl.org/dc/terms/conformsTo"
    rdf-graph="#manifest"></a>
  <a hidden href="#manifest"
    rdf-subject=""
    rdf-predicate="https://ia2.dev/spec/resource-envelope#manifestGraph"
    rdf-graph="#manifest"></a>
  <a hidden href="https://greeting.hare.invalid/"
    rdf-subject=""
    rdf-predicate="https://ia2.dev/spec/resource-envelope#virtualBase"
    rdf-graph="#manifest"></a>
  <a href="#greeting"
    rdf-subject=""
    rdf-predicate="http://purl.org/dc/terms/hasPart"
    rdf-graph="#manifest">Greeting resource</a>
</section>

Semantic HTML representation

<a hidden href="#greeting-representation"
  rdf-subject="#greeting"
  rdf-predicate="https://ia2.dev/spec/resource-envelope#representation"
  rdf-graph="#manifest"></a>
<a id="greeting-representation" hidden
  href="https://ia2.dev/spec/resource-envelope#DOMRepresentation"
  rdf-subject="#greeting-representation"
  rdf-predicate="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
  rdf-graph="#manifest"></a>
<data value="/hello.html"
  rdf-subject="#greeting-representation"
  rdf-predicate="http://purl.org/dc/terms/identifier"
  rdf-graph="#manifest">/hello.html</data>
<data hidden value="text/html"
  rdf-subject="#greeting-representation"
  rdf-predicate="http://purl.org/dc/elements/1.1/format"
  rdf-graph="#manifest"></data>
<a hidden href="#greeting-content"
  rdf-subject="#greeting-representation"
  rdf-predicate="https://ia2.dev/spec/resource-envelope#carrier"
  rdf-graph="#manifest"></a>
<template id="greeting-content">
  <article><h1>Hello</h1><p>Welcome, agent.</p></article>
</template>

Optional byte representation

<a hidden href="#source-representation"
  rdf-subject="#greeting"
  rdf-predicate="https://ia2.dev/spec/resource-envelope#representation"
  rdf-graph="#manifest"></a>
<a hidden
  href="https://ia2.dev/spec/resource-envelope#ByteRepresentation"
  rdf-subject="#source-representation"
  rdf-predicate="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
  rdf-graph="#manifest"></a>
<data hidden value="text/plain; charset=utf-8"
  rdf-subject="#source-representation"
  rdf-predicate="http://purl.org/dc/elements/1.1/format"
  rdf-graph="#manifest"></data>
<data hidden value="5"
  rdf-subject="#source-representation"
  rdf-predicate="https://ia2.dev/spec/resource-envelope#byteLength"
  rdf-datatype="http://www.w3.org/2001/XMLSchema#nonNegativeInteger"
  rdf-graph="#manifest"></data>
<data hidden value="sha256-LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ="
  rdf-subject="#source-representation"
  rdf-predicate="https://www.w3.org/2018/credentials#digestSRI"
  rdf-datatype="https://www.w3.org/2018/credentials#sriString"
  rdf-graph="#manifest"></data>
<a hidden href="#source-bytes"
  rdf-subject="#source-representation"
  rdf-predicate="https://ia2.dev/spec/resource-envelope#carrier"
  rdf-graph="#manifest"></a>
<script id="source-bytes" type="application/octet-stream"
  data-encoding="base64">aGVsbG8=</script>

Introduction

Design goals

Non-goals

Conceptual model

Graph identity and logical paths

Resource and representation

Canonical retrieval locations

Relations and derived artifacts

Envelope document conformance

Canonical manifest

Manifest discovery algorithm

HARE vocabulary

Classes

Properties

Reused vocabulary

Specification and artifact profiles

Validation shapes

Representation model

DOM representations

Byte representations

Carrier processing

Byte commitments

Virtual document URLs and logical paths

Human presentation

Optional runtime model

Host Content Security Policy compatibility

Verified subresource materialization

Artifact profiles

Implementation conformance

Envelope Producer

Envelope Consumer

Viewer Runtime

Materializing Viewer Runtime

Archival Consumer

Validator

Security and trust

Byte, semantic, and source integrity

Relationship to adjacent formats

Examples

Envelope and manifest declaration

Semantic HTML representation

Optional byte representation

Minimal viable 0.1

Open questions

Recommendation