Skip to content

Use props consistently for component inputs #177

Description

@taras

Why

A component declares caller-supplied values under inputs, but callers pass them as props and component bodies read them through props. The same concept therefore has two public names:

inputs:
  name:
    type: string
Hello, {props.name}

The declaration should use the same vocabulary as invocation and consumption.

This also establishes a clear vocabulary for structured component returns in #176:

  • meta is component-owned configuration;
  • props are values supplied by the caller;
  • content is rendered Markdown text;
  • a component return value is declared by returns;
  • Result<T> remains available for execution success or failure.

Desired contract

Markdown components declare props directly:

required: [name]

props:
  name:
    type: string

The full JSON Schema form uses the same key:

props:
  type: object
  properties:
    name: { type: string }
  required: [name]
  additionalProperties: false

Function components use the same term for their exported schema.

Rename surface

Apply the terminology consistently across the public and internal component contract, including:

  • Markdown frontmatter inputsprops;
  • function component export const inputsexport const props;
  • ComponentDefinition.inputs.props;
  • inspectDocument().inputs.props;
  • InputSchemaPropsSchema;
  • input-schema parsing, compilation, validation, errors, tests, examples, and specifications;
  • repository components and fixtures that declare the old key.

Prefer names that describe props rather than retaining input in adjacent APIs such as schema compilation helpers.

Compatibility

This is a breaking vocabulary correction, not a second spelling. Do not retain inputs as a compatibility alias. A document using inputs after the rename treats it according to the ordinary frontmatter metadata rules rather than silently declaring props.

The concise/full schema behavior from #172 remains unchanged; only its declaration vocabulary changes.

Relationship to component returns

This issue does not implement #176. It reserves a coherent direction for that work:

returns:
  type: object
  properties:
    passed: { type: boolean }

When returns is absent, the component return value remains its rendered text string, equivalent to an implicit { type: "string" } contract. A declared returns schema overrides that default. The mechanism for producing a non-text value, content interaction, validation, journaling, and replay remains in #176.

Acceptance criteria

  • Markdown and function components use props for their caller-supplied schema.
  • Component definitions, inspection, validation, and diagnostics expose the same term.
  • All repository documents, fixtures, examples, and specifications use the new vocabulary.
  • No public inputs compatibility alias remains.
  • Existing full and concise schema behavior is unchanged after replacing the key.
  • Generated --props-*, XMD_PROPS_*, aggregate props, and programmatic props continue to work unchanged.
  • The change is covered by root, imported-component, function-component, inspection, and CLI tests.

Sequence

Implement after #175 and before positional prop arguments in #173. Coordinate terminology with #176, but keep structured return behavior out of this change.

Related: #172, #173, #176

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions