Skip to content

Allow concise input declarations for Markdown components #172

Description

@taras

Why

Markdown components currently repeat the enclosing object schema even when they
only need to declare a few named inputs:

inputs:
  type: object
  properties:
    name:
      type: string
  required: [name]
  additionalProperties: false

The object shape is an implementation invariant, not useful information for
most document authors. A concise form would make input declarations easier to
read while preserving the existing JSON Schema contract internally.

Proposed authoring form

required: [name]

inputs:
  name:
    type: string
  loud:
    type: boolean
    default: false

Normalize this before compilation to:

type: object
properties:
  name:
    type: string
  loud:
    type: boolean
    default: false
required: [name]
additionalProperties: false

Property definitions remain draft-07 JSON Schema. The shorthand only makes the
enclosing closed object implicit.

Contract

  • Shorthand applies to every Markdown component, whether imported or executed
    as the root document.
  • inputs.type: object selects the existing full JSON Schema form.
  • Otherwise inputs is a map of property names to property schemas.
  • Top-level required belongs to shorthand.
  • Full JSON Schema keeps required inside inputs.
  • Supplying top-level required with the full form is a configuration error;
    the two lists are never merged.
  • Shorthand normalizes to additionalProperties: false.
  • An absent inputs declaration retains the existing empty closed schema.
  • Frontmatter inspection and execution use the same normalization path.

Acceptance

  • A shorthand component receives and validates props exactly like the
    equivalent full schema.
  • Required properties and recursive defaults behave identically in both forms.
  • Imported and root Markdown components share the behavior.
  • Invalid property schemas fail during frontmatter/schema validation.
  • Ambiguous or mixed shorthand/full declarations fail with a useful
    diagnostic.
  • Existing full schemas remain unchanged.

Scope

This issue does not add positional command-line arguments. That work consumes
the normalized schema in a separate follow-up.

Related: #171

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