Skip to content

Canonicalize pattern reference syntax and documentation #170

Description

@irl-dan

Problem

OpenProse pattern references are conceptually supported but documented inconsistently. The relationship among use, pattern:, with:, and config: lacks one canonical, cross-linked definition. ### Patterns appears in repository examples/tests but is absent from the canonical Contract Markdown section table, and some documentation references a nonexistent Forme pattern-expansion section.

This makes it difficult for Compose and authors to distinguish importing a pattern, instantiating it, binding its slots, and configuring it.

Desired property

One self-evident authoring path explains how a Contract references and instantiates local and external patterns, how dependency installation and aliases apply, how slots/config are validated, and how Forme expands the instance. Examples and canonical section tables agree.

Smallest plausible change

  • Choose and document the canonical placement for pattern instances.
  • Define use, pattern:, with:, and config: together with one complete example.
  • Decide whether ### Patterns is canonical; add it to Contract Markdown or remove/migrate its uses.
  • Repair broken Forme cross-references.
  • Add a conformance test guarding the chosen form.

Alternatives

  • Introduce new pattern-import syntax.
  • Keep pattern instances as free-form YAML and document only conventions.

No new syntax is recommended until the existing surface is made internally consistent.

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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions