Input-Form Descriptor

The input-form descriptor is a presentation view of a method's inputs: for each pipe, an ordered list of field descriptors that a renderer turns into a fill-in form with no schema heuristics, no hardcoded native-concept table, and no description matching.

{
  "legal.summarize_contract": {
    "fields": [
      {
        "kind": "document",
        "name": "contract",
        "concept_ref": "legal.Contract",
        "refines": ["native.Document"],
        "description": "The contract to summarize",
        "required": true,
        "presence": "plain",
        "gating": true
      },
      {
        "kind": "prose",
        "name": "instructions",
        "concept_ref": "native.Text",
        "description": "Optional steering instructions",
        "required": false,
        "presence": "optional",
        "gating": false
      }
    ]
  }
}

A renderer reading that descriptor knows to offer a file control for contract because the descriptor says the concept refines native.Document — not because it recognized a url property in a schema, and not because the description contained the word "document". That is the whole point of the artifact: every fact a form needs is stated, so the guessing that a JSON Schema forces on a renderer stops being necessary.

The descriptor exists because a schema is a lossy projection of a method's inputs. Projecting a concept onto JSON Schema destroys concept identity, the refinement chain, the authored presence marker, a fixed item count, and the measured meaning of a default — and a renderer that needs those back can only re-infer them, imprecisely and differently in every consumer. The descriptor states them instead, deriving from the same resolved library the schema does, so the two cannot disagree.

The descriptor is a recommended extension field of the HTTP Runner Protocol's validate response, where it rides the field name input_form. It is equally derivable offline from a resolved library, with no server involved; how a caller asks a particular implementation for it is that implementation's decision, and outside this standard.

Specification Status

This document specifies an artifact implementations already produce, and makes it standard-owned so that independent implementations agree on it by conformance rather than by imitation. Where a rule below names behavior an implementation has not yet realized, it is the forward contract that implementation is brought into conformance with — the same convention Library Crate Format uses.

Two slots are shaped now and filled by the language later. examples and the text and numeric constraint slots are on the wire because the descriptor's shape should settle once: an implementation may already hold such facts about a concept's payload, and the language will grow the authoring side without reopening the wire. A producer that has nothing to put in them omits them.

Until the language defines how such a fact is authored, these are the one part of the artifact whose content is a producer's own, and the standard says so rather than pretending otherwise: two conforming implementations agree on every language-derived slot and may differ on whether they fill these. A consumer reads them as advisory enrichment and never as a fact it depends on, and the comparability guarantee below is stated over the language-derived slots.

The Per-Pipe Descriptor

The artifact is a map from namespaced pipe reference to one descriptor object, over the same key set as pipe I/O contracts — the descriptor is per pipe input, and that map's key space is its natural address. Keys are fully-qualified pipe_refs (domain_path.pipe_code).

Each entry is an object with one member: fields, an ordered list holding one field descriptor per declared input slot, in authored input order.

Order is why the descriptor is a sibling artifact rather than a decoration inside each contract's input entry. A form is ordered; the contract's inputs map deliberately contracts no order. The list carries the order as a fact, and the contract stays byte-stable whatever a renderer asks for.

A pipe with no inputs maps to {"fields": []}. An empty form is a valid form, not an omitted entry.

Field Descriptors

A field descriptor is a recursive object, discriminated on kind: one node per rendered field. An object node recurses through fields, a list node through item.

The vocabulary is field kinds and semantic slots — bounds, choices, defaults — and never control names. How a renderer maps a kind to a control is the renderer's decision, and this document deliberately names no controls.

Common Slots

Every field descriptor carries:

A slot that does not apply to a node is absent, never null. Applicable falsy values (required: false, integer: false) are stated.

Gating

gating is the single answer to "must the user put something in before the run may start", and a renderer blocks the run on exactly the top-level descriptors whose gating is true (a nested field gates through its parent).

It is stated rather than left to a consumer to re-derive, because it is not the same question as required:

The rule is presence != "optional" and not (kind == "list" without item_count). The variable-list row is the one that makes the two facts distinct: such a slot is required — a caller must send the property — yet a renderer submitting [] for it has satisfied the method, so blocking the run there would demand something the method never asked for. Stating gating on the wire is what lets a later language-level minimum change the answer without touching a single renderer.

Field Kinds

kind is a closed union. This version of the standard defines:

document and image carry no accept-list and no upload affordance: what the value is rides concept_ref and refines, and how a renderer offers a file is the renderer's decision.

unknown is the escape hatch, and it is mandatory rather than optional: a producer that cannot map a node honestly MUST report unknown rather than guess a kind. A renderer then falls back to raw entry against the slot's json_schema. A derivation is total — every node gets a descriptor — and unknown is what makes totality truthful.

The constraint slots (min_length, max_length, pattern, format on the text kinds; the four numeric bounds on number) are stated where a producer holds them. format is an open string set carrying schema formats the date kind does not absorb (time, uri, …).

Kind Assignment

Kind is decided from stated facts — a concept's identity, its refinement chain, its resolved structure — and never by sniffing a schema's shape or matching a description. A concept refining native.Document is kind: "document" because it says so, not because its payload happens to hold a url property.

A concept-typed node takes its kind from what the concept resolves to. The rows below are tried in order, and the first one that matches decides:

The order is the rule, not a formatting accident. Most natives declare a structure of their own — native.Document is a url, a mime_type, a filename — so a table that asked about structure first would put every native and every native-backed concept on the object arm and never reach the native rows at all. legal.Contract refines native.Document is kind: "document", not an object of url and mime_type, and it is the ordering that says so.

The chain is walked rather than the concept read alone because the language keeps refines and structure mutually exclusive: a refining concept never carries a structure of its own, so inheritance along the chain is the only way one reaches the object arm — and a chain that reaches a native reaches it through that native's structure, which is exactly the case the native rows catch first.

A concept that resolves to no structure is text-valued, per the language's own rule that a description-only concept is text — and the chain clause matters: Foo refines Bar where Bar is description-only resolves to no structure just as Bar does, so it is prose and not the unknown a literal reading of the concept alone would give. That fact reaches the wire as kind: "prose" and never as a fabricated refinement link: the language states description-only text-valuedness as an arm of its own, not as refinement of native.Text, and a producer inventing that link would be reporting ancestry no one authored — precisely what the derivation requirement below forbids. A consumer asking "is this text-valued?" reads kind; refines answers the different question "what does this specialize?", and on a structureless concept the honest answer is nothing.

A native concept maps by identity, over the pinned definitions:

A structure field maps from its declared field type — except that a field carrying choices is an enum, which the language already guarantees by requiring type to be omitted there:

dict is unknown rather than a kind of its own because the language's dict declares a key type and a value type, not a set of fields, and a form built from that would be guessing at entries the method never named.

Structured Multiplicity

Plurality is a stated fact and is never re-derived from a schema's type: "array":

• An input slot authored Concept[] is a list field whose item describes the concept, with no item_count.
• An input slot authored Concept[N], N ≥ 2, is a list field with item_count: N — the fixed count as a structured fact.
• A nested structure field of list type is likewise a list node, its item derived from item_type and, where that is "concept", item_concept_ref. A field that declares no item_type, or whose element type the field blueprint cannot express (a list of lists, a list of dicts), is still a list node — the plurality is stated — carrying item with kind: "unknown".
• Concept[1] is single — one item, no list framing — exactly as in pipe I/O contracts, so a stated item_count is always greater than one.

item_count is absent when it does not apply. The contract makes the opposite choice and carries the slot as null off the fixed arm; the two artifacts differ deliberately, and each states its own rule so that neither is guessed from the other.

On a list node, concept_ref and refines name the element concept — the authored reference with its multiplicity suffix stripped, exactly as the contract reports it — and the item descriptor carries the same concept_ref. The list node is where a renderer reads the slot's identity; the item is what it renders once per entry.

Intent Hints on a Descriptor

Every field descriptor carries an optional hints object: the node's effective intent hints, a flat map of string to string.

The value is the final key-by-key merge the language defines — along the concept's refinement chain, nearer declaration winning, and then the site layer (a structure field's or an input slot's own hints) over the concept layer — so a consumer reads one map and walks nothing. Everything well-formed rides it, unknown keys and unknown words included: content leniency is the language's rule, and a descriptor preserves content for consumers that know more than this version does.

On a plural node the merged hints appear on the list node and on its item, mirroring the concept_ref duplication: applicability is judged per item, and a renderer reading either node finds the same answer.

A node with no effective hints has no hints member, so a hint-free method's descriptor is byte-identical to what it would have been before hints existed.

An applicable intent word is an input to kind assignment, never a second answer competing with it. On a text-valued node, an effective intent = "prose" yields kind: "prose" and intent = "label" yields kind: "text". An absent, unknown, or inapplicable word leaves the kind that kind assignment already decided. rating and quantity never change a kind — both describe a number, and this version's union has no finer kind — and ride the slot for the renderer.

Applicability is judged exactly as Intent Hints defines it, which is narrower than a kind: a text node carrying format: "time" is neither text-valued nor number-valued, so no word of this version applies to it.

The language's two governing rules bind the slot, and neither is weakened by the descriptor carrying it: hints are non-normative — no hint changes a verdict, the gating rule, or the payload contract — and a renderer that ignores hints stays correct, because the kind assignment above is complete without them.

Strictness

Every object this document defines — a per-pipe descriptor, a field descriptor — is a closed shape. A producer MUST NOT emit a member this version of the standard does not define, and a consumer MAY reject one. An unrecognized member is version drift, and catching it where a payload is parsed is more useful than discovering it three layers later.

The hints map is the deliberate exception, and it is an exception in content, not in shape: its shape is fixed — a flat map of string to string — while unknown keys and unknown words inside it are carried through, exactly as the language's leniency rule requires.

This strictness is the opposite of the protocol's extension policy, which keeps the validate report extension-open: an implementation may add fields to the report — that is how this artifact reached the report in the first place — but it may not add members inside the artifact and still call it an input-form descriptor. The report is the envelope and grows; the artifact is the view and does not. Growth happens through the standard, as a minor version.

Derivation Requirements

• Derived from the resolved library, never from a projected schema. Deriving the descriptor from a JSON Schema would re-import every loss the descriptor exists to end. The descriptor and the contract's json_schema are two projections of one library, which is why they cannot disagree.
• The refinement chain needs pre-flattening facts. refines reports the chain as authored, and the crate's normalization step 3 deliberately flattens in-crate structured refinement away. A producer therefore derives the descriptor from the closure before that flattening — fully qualified and native-materialized, with its refines links intact. A producer holding only a normalized crate derives every other slot unchanged and reports the refines link normalization retains — the terminal native.<Code> link, where the chain reaches one, which is what the membership test consumers run on refines depends on. It MUST NOT reconstruct intermediate links it does not hold.
• Deterministic. The same library yields the same descriptor: field order is authored order, and no content depends on the environment or on the request.
• One derivation, every surface. An implementation that reports the descriptor from more than one path MUST derive it through one shared derivation, so the artifact cannot differ by which backend answered.
• Same projection from every engine. The derivation is mechanism-free — nothing in it requires a network, a model, or a server — so two independent implementations derive the same descriptor from the same library, and their outputs are comparable as values. The slots the language does not yet author are the stated exception: comparability is asserted over the slots this version derives from the library.

Non-Goals

• No widget vocabulary. Kinds and hints name intent; textarea, slider, and dropdown never appear on this wire.
• No validation semantics. The descriptor never becomes something a machine consumer must read to validate a payload — json_schema keeps that job. A caller ignoring the descriptor entirely loses no fact it needs.
• No layout or styling. Field order is the authored order, not a layout. Grouping, sizing, and theming belong to consumers.
• No committed artifacts. The descriptor is derived on demand. Nothing is generated into a consumer's repository, stamped, or locked.
• No result presentation. The descriptor describes a method's inputs. Presenting what a run produced is a separate concern this artifact does not address.

Relationship to Other Specifications

• .mthds File Format defines the input slots, concepts, and structure fields the descriptor projects.
• Library Crate Format defines the resolved library the descriptor derives from — the authority on refinement, presence, multiplicity, and defaults.
• Pipe I/O Contracts is the machine contract over the same pipes, keyed by the same pipe_ref set, and carries the json_schema the unknown kind falls back to.
• Intent Hints owns the hint vocabulary the hints slot carries; this page defines only how the effective merge reaches the wire.
• Native Concept Definitions pins the native concepts the kind-assignment table maps.
• HTTP Runner Protocol carries the artifact as a recommended extension field of the validate response.