Specification: 1.0
Surface document: 1.0
Action message: 1.0
Component catalogue: 1.0
Component specification: 1.0
Web protocol: 1.0
An application can publish a structured description of its current interface. This description is called a surface. It contains pages, content, values, input definitions and actions.
A viewer checks the surface and presents it with controls suited to its platform. The application keeps control of data, permissions, validation and business results. The viewer controls layout, focus, navigation and local controls.
The same surface can support web, desktop, phone, terminal, kiosk, voice, print and other compatible viewers. These viewers may look different. They MUST preserve the same information, state and actions.
MUST and MUST NOT state requirements. SHOULD states a recommendation that may have a documented exception. MAY states an option.
The schemas and component catalogue define exact data shapes. The component specification defines the standard components and their presentation requirements.
The application owns:
- business data and rules;
- identity and permissions;
- final validation;
- available actions;
- state changes and action results.
The application MUST validate every action. It MUST NOT rely on the viewer to enforce security or business rules.
The viewer owns:
- loading and validating the surface;
- layout and platform controls;
- focus, scrolling and navigation;
- user accessibility settings;
- safe use of local capabilities;
- action submission and result display.
A viewer MUST NOT execute publisher JavaScript, HTML, CSS, templates or arbitrary commands to present a surface.
A renderer is the part of a viewer that turns components into controls or other output. It may use native controls, composed controls, terminal views, speech or another suitable form.
A surface is a JSON object served as application/lumui+json.
Its main fields are:
lumui_surface: surface version;app_id: application identifier;surface_id: logical surface identifier;revision: version of the represented application state;title,localeanddirection;requested_page_id: page to open;pages: available pages and regions;actions: actions the user may request;links: this and related resources.
The surface schema rejects undeclared fields. A viewer MUST validate the document and its references before it binds actions or uses privileged capabilities.
Page, component and action IDs MUST remain stable within their declared scope. They identify meaning. They are not CSS selectors or layout instructions.
The application MUST change revision when state can affect the displayed page, accepted input or available actions. It MUST reject an outdated action when accepting it could produce a wrong or unsafe result.
A page is one view or step in a task. Regions group related content, such as navigation, a form, a summary or a footer.
The surface MUST include every essential region, including application headers, menus, navigation and footers. A viewer may move or collapse a region, but MUST NOT silently remove required content or destinations.
Document order defines the reading and interaction order. Visual layout may differ.
Every component has a registered kind. The component catalogue states its required, optional and forbidden fields. A renderer MUST follow the matching entry in the component specification.
An unknown optional component needs a clear fallback when omission matters. An unknown required component MUST fail clearly when no safe fallback exists.
The preview component contains one standard component. It permits a separate preview layout, but does not load another surface or change the viewer, device or accessibility context. A renderer without a preview layout renders the contained component normally.
A device profile describes the viewing conditions and supported input and output. It may change:
- region placement;
- columns and grouping;
- control choice;
- navigation style;
- scrolling, paging or progressive disclosure;
- visible density.
A profile MUST NOT change application meaning, action identifiers, required input or essential content.
Required content and controls must remain reachable. A viewer uses wrapping, reflow, scrolling, pagination or another suitable method. It MUST NOT solve overflow by clipping labels, values, errors or actions.
Examples include:
- desktop navigation beside content;
- a one-column phone layout;
- keyboard menus and dialogs in a terminal;
- large guided controls on a kiosk;
- spoken sections and named choices in a voice viewer;
- stable reading order in print.
Scaling a fixed desktop page is not a complete device profile.
Presentation controls how a task is arranged. A viewer may support standard, guided, focus, glance or other registered modes.
A mode MUST retain essential content and actions. A summary mode must identify itself and provide a direct route to the complete surface.
Appearance values such as color, type, spacing, radius and motion are preferences. They MUST NOT change information, permissions, validation or action availability.
Application branding applies inside application content. Accessibility settings and viewer policy take priority.
The publisher supplies labels, roles, values, states, relationships, errors and alternatives. The viewer maps them to the accessibility features of its platform.
Every required input and action MUST work without a pointing device unless the task itself depends on a path or spatial gesture. Focus order follows the reading and task order.
A viewer applies text size, contrast, color, motion and other accessibility settings while choosing controls and layout. It MUST NOT rely only on scaling a completed fixed screen.
Loading, errors, validation, completion, selection and expanded state must be available to assistive technology. Color and animation cannot be the only way to communicate state.
Images, audio and video need the alternatives required for their audience. A viewer exposes supplied alt text, captions, transcripts, descriptions, attribution and licence links.
Inputs provide a label, purpose, current value, limits and validation information. Placeholder text is not a replacement for a label.
The viewer may check input early, but the application makes the final decision.
An action has a stable ID, a target, an input contract and any required consequence or confirmation information. A viewer sends the declared ID. It MUST NOT infer an action from visible text, position or icon.
An action request contains:
- action-message version and message ID;
- surface ID and revision;
- component and action IDs;
- declared input;
- source context.
The application checks identity, permission, revision and input before changing state. Its result distinguishes success, validation failure, missing permission, conflict and transport failure.
After an accepted state change, the application returns a new surface, navigation result or explicit update. The viewer replaces local displayed state with that result.
The viewer prevents accidental repeated activation while an action is pending. The application provides idempotency or duplicate detection when repetition could cause harm.
One HTTP or HTTPS route may provide ordinary HTML and a surface.
A compatible viewer can request:
Accept: application/lumui+json, text/html;q=0.8An HTML response may advertise its surface with an alternate link of type application/lumui+json. The same relationship may appear in the HTTP Link header.
An origin SHOULD expose discovery at /.well-known/lumui. Discovery identifies the service descriptor. The descriptor URL belongs to the publisher. /lumui/descriptor.json is used only by the reference implementation and is not a required private route convention.
Surface, action and supporting-resource URLs come from discovery, descriptors or links. Relative URLs resolve against the response that declares them.
The entered application URL remains the history entry. Loading a descriptor or alternate representation MUST NOT silently replace it.
A viewer that claims media support either plays a supported source or shows a clear fallback. Loading must end in playback, failure, cancellation or timeout.
Media players keep supplied source, poster, captions, transcript, audio description, attribution and licence information available. A viewer MUST NOT invent any of this information.
File, contact, media and location selection use trusted viewer or operating-system controls. Application content MUST NOT imitate permission dialogs or other trusted controls.
Maps and calendars need usable non-graphical alternatives. A map may become a location list or route summary. A calendar may become a chronological date list.
Surfaces, links, media information and action results are untrusted until checked.
A viewer MUST limit document depth, text and collection size, redirects, downloads, image dimensions, decompression and media buffering. Exceeding a limit fails safely and produces a useful diagnostic.
A surface MUST NOT cause arbitrary code or shell execution, unrestricted file access or privileged device access.
Cookies, tokens and other credentials are isolated by the applicable origin or security scope. Authentication prompts identify the requesting origin and remain distinct from application content.
The viewer sends only the capability and user information required for the exchange. Credentials, accessibility settings, history and protected input stay local unless the protocol and disclosed policy require otherwise.
Diagnostics hide secrets by default.
Publishers and viewers state the versions and profiles they use or accept. If no compatible version exists, they fail clearly and MAY offer another representation. They MUST NOT guess action meaning.
An extension has a collision-resistant identifier or uses an applicable registry. It states whether it is optional or required and defines a fallback where one is safe.
An extension MUST NOT silently change the meaning of a standard component, action or state. A new meaning requires a new extension identity or versioned update to the catalogue, schema and component specification.
A custom renderer may present a standard component differently. It still preserves the component's fields, state, actions, validation, accessibility and fallback.
A conformance claim states:
- implementation and release;
- publisher, viewer, renderer, action processor or gateway class;
- supported protocol versions and profiles;
- supported components, transports and output platforms;
- accessibility test environments;
- known limitations;
- test evidence.
Tests should include malformed surfaces, unknown components, large input, outdated and repeated actions, validation errors, keyboard and focus behavior, media failure, origin changes, cancellation and recovery.
Conformance depends on behavior, not visual similarity.
The reference website publishes:
/specification/protocol.json/specification/component-catalog.json/specification/lumui-components.md/specification/schemas/surface.schema.json/specification/schemas/service-descriptor.schema.json/specification/schemas/discovery.schema.json/specification/schemas/action-message.schema.json/specification/lumui-specification.md
The schemas and component catalogue define exact fields and values. The component specification defines standard component behavior. Examples help implementation but do not override these resources.