Wikifunctions:Type proposals/HTML fragment structure

initial draft — early comments welcome

Summary

A structured representation using which an HTML fragment may be specified, or an existing fragment fully defined.

Uses

• [Why should this exist?]
• Allows functions to construct content that is ultimately intended to be rendered as HTML without prematurely serialising to HTML.
• Allows existing HTML to be represented as a Wikifunctions object that can be supported by the Wikifunctions and Abstract Wikipedia user interface

??input argument to a function

The following example uses existing functions to construct an HTML fragment whose arguments are themselves composed from smaller values. In particular, the text content is assembled from different string-like components and the lang attribute is assembled from multiple string components, illustrating how this representation avoids premature serialisation while remaining fully evaluable.

A simple example.

In this case, the original structure of the text content is lost, which would not generally be true of the proposed structure. The original structure of the tag-name and attributes, however, would always be irrecoverable (which is a good reason to avoid premature serialisation).

• [What kinds of functions would be created using this?]
• Abstract content transformers, typically language-specific, like…
• Abstract content formatters, typically language-neutral, like…
• HTML pipeline inverters (parsers), typically language-neutral (not currently supported)
• What standard concepts, if any, does this align with?

…

Structure

Description of what a value of this type would look like and why

The structure that is intended to be used is a Typed list (Z881). This proposal defines the Type (Z4) for one element in such a list. This separates the fragment content from its nested wrappers.

Fragment content must be a list of “string-like” objects, which may be empty. A “string-like” object must be one of String (Z6), Monolingual text (Z11), HTML fragment (Z89) or an object of the new type (which is serialisable as a canonical string representation). Other “string-like” types might be supported.

Associated with the fragment content is a list of tag-names and, for each of those, a list of attributes and their values (as a Typed pair (Z882) with each element being a Typed list (Z881)). These are all lists of strings, so an attribute like lang="en-GB" can be supplied as (informally) {["lang"], ["en", "-", "GB"]}, avoiding the need for string concatenation prior to serialisation. Any of the lists may be empty.

Example values

Value …

{   "type": "…", "value": "…" }

{   "Z1K1": "Zxyz", "ZxyzK1": "…" }

Validator

The validator ensures that:

Identity

Two HTML fragment structure objects are the same if their serialised string representations are the same. This implies a canonical string representation, which is also implemented by the converters to code.

Converting to code

An object is serialised as a canonical string representation (which may be immediately assigned to the Z89K1 value for an HTML fragment (Z89) in a ZObject construction).

Python

…

JavaScript

…

Converting from code

A canonical string representation is parsed to its structured form. This is a non-trivial operation, and initial implementations targeting an ad-hoc structure should be available before this proposal is finalised.

Python

…

JavaScript

…

Display function

How would a value of this type be displayed on Wikifunctions Convert to HTML fragment (Z89), allowing a rendered result and (only on wikifunctions.org) the underlying JSON, as well as expansion to the full object form. Embedded functions would just display the rendered result.

Read function

When entering a value for this type as a string, what format should that string have?

The input string must be text appropriate for the value of Z89K1 (as for HTML raw content to HTML fragment (Z27861)). In the worst case, no structure can be inferred from the HTML fragment (Z89) thus constructed. That simply means that the result from evaluating the read function is an object containing a single Z89, with the tag and attribute lists being empty, and this could eventually be serialised as a Z89 that will not render correctly (for example, invalid tags would be visible as text content).

Alternatives

In order to capture the idea presented in the summary, what alternative structures, display functions, read functions, etc. could have made sense too? …

Comments

For general comments, please reply to the proposer.

•  Support as proposer. --GrounderUK (talk) 13:16, 29 April 2026 (UTC)
• Weak oppose as long as the [ ([ "lang" ], [ "en", "-", "GB" ]) ] thing is part of the proposal. String dicts for attributes and nesting of elements to arbitrary depth is one thing, but allowing any of the leaf objects to be either a string or a list is asking for trouble. (It also won't work atm because a map can only use Z6 as its key type, see tests on Z883.) YoshiRulz (talk) 00:51, 12 May 2026 (UTC)