Data surfaces

One surface, every door

This models the event registration example that ships in the data_surface_examples module: the settings for one event, with a venue, a room, a capacity, a ticket and a contact. Compliance is a second example module that adds a licence and stewards. It is a drawing of that example, not a live copy of it.

Declare the shape once

A surface says what a thing takes: its keys, their types and their limits. It says nothing about forms, routes or tools.

Everything that needs those values reads the same contract. A form, a React page and an agent accept and refuse exactly the same things.

Turn the model, pick a layer above, or change a value below and watch it reach every door.

Today: written twice, and they never meet

A form array describes the inputs with their callbacks, its validation and its submit handler. A tool plugin lists the same inputs again, with its own constraints and its own save.

Each is real work, and neither reads the other. Another module alters the form. The tool never hears about it, so a call with 150 is saved although the form would refuse it. To close the gap the module has to write its rule a second time.

A headless admin has nothing to draw from. The form's rules are PHP callbacks, and the tool's inputs carry no dependencies between keys.

Change the licence below. Only the form's doors light up.

Side by side

On the left, the inputs are written twice and nothing is shared. On the right, one declaration that every door reads before anything is submitted.

	Today	With a surface
The inputs are described	twice	once
Another module's rule reaches	the form, unless written again	every door
The form and the tool share	nothing	the whole contract
A dependency between keys lives in	a PHP callback	the contract
A headless admin	has nothing to draw from	draws from the schema
A new consumer	writes its own copy	reads the contract

The surface

One class declares the inputs. Each key is an ordinary typed data definition with ordinary constraints.

A target underneath loads the current values and commits the new ones, so the surface never knows where they are stored.

Subsurfaces

A surface can dock another surface at one of its keys. The part keeps its own keys, refinement and validation, and the parent cannot reach into it. That is what makes Contact reusable anywhere.

A slot is a key whose part depends on another value. Pricing decides whether the free ticket or the paid ticket is docked.

Refinement

Some keys are only fully known once another value is. A refiner is a method that names the key it narrows. Its parameters are the keys it watches, so the signature is the dependency.

A refiner may only tighten what was declared. Room narrows to the venue's rooms, and capacity stops at the room's seats.

Others get a say

Another module can add keys to a surface it does not own, stored under its own name. It can tighten the owner's keys and say where its fieldset is drawn.

Here Compliance adds a licence and stewards. Without a licence it holds capacity at 100. The owner's class is not touched.

The contract

Ask the surface with the values so far and it answers with its shape as it stands: JSON Schema, with labelled choices as oneOf and slots as if / then.

Nothing in it depends on who is asking.

Change a value

pricing

licence

The contract changes once. Every door gets the same answer.

Owner's surface
Subsurface
Another module
Refinement
Written by hand today
Contract going out
Values coming in

Drag to turn. Shift-drag, right-drag or two fingers to move.
Scroll or pinch to zoom. Pick a door to see what it reads.

The 3D model needs WebGL, which this browser did not provide. The layers are still described in the panel.