Skip to content

[Feature Request] Schema inheritance: extend and override a parent schema #778

Open
Open
[Feature Request] Schema inheritance: extend and override a parent schema#778
Labels
design-reviewNeeds product/design decision

Description

@pacaplan
pacaplan
opened on Feb 28, 2026

Problem

openspec schema fork creates a flat copy with no ongoing relationship to the original. If you only want to change one or two artifacts (or the apply section), you still have to duplicate the entire schema.

Request

Support an extends field so a schema can inherit from a parent and only declare what it overrides.

Requirements

  • A schema can declare a parent via an extends field (e.g., extends: spec-driven)
  • Child artifacts override the matching parent artifact by id; unspecified artifacts are inherited as-is
  • The apply section can be overridden independently
  • Resolution should be shallow (one level) to keep behavior predictable

Example

name: my-workflow
extends: spec-driven

artifacts:
  - id: proposal
    # overrides only the proposal artifact; all others inherited from spec-driven
    instruction: |
      Custom proposal instructions here.

apply:
  requires: [tasks]
  instruction: Custom apply instructions.

Activity

  1. pacaplan commented on Mar 1, 2026

    @pacaplan
    pacaplan
    on Mar 1, 2026
    Author

    @1code-async please analyze this issue.

  2. 21st-connector commented on Mar 1, 2026

    @21st-connector
    21st-connectorBot
    on Mar 1, 2026 – with 21st - Connector
    Contributor

    @pacaplan Sorry, only collaborators with write access can trigger @1code.

  3. fordarian commented on Mar 13, 2026

    @fordarian
    fordarian
    on Mar 13, 2026

    This is exactly the feature I would like to have as well! Currently, to add an additional step (such as UI wireframes for my current use case) I need to fork the entire schema. After future OpenSpec updates, I'll have to manually merge my changes again, which increases maintenance complexity (

  4. jiehu5114 commented on Apr 24, 2026

    @jiehu5114
    jiehu5114
    on Apr 24, 2026

    +1 on this. I'm maintaining three workflow schemas (iOS, Android, HarmonyOS) and about 60% of the artifact instructions are identical across all three. Right now the only option is copy-paste, so every time I tweak wording in one schema I have to remember to update the others.

    While full schema inheritance would be the ideal fix, it's a fair amount of merge logic to get right. A simpler stepping stone might be an instruction_file field on each artifact — just a path relative to the schema directory that gets loaded at runtime instead of inlining the text:

    artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    instruction_file: ../shared/instructions/proposal.md  # shared across schemas

    This way you can keep common instructions in one place and still have per-schema templates. It's maybe a 20-line change to instruction-loader.ts and doesn't require any merging logic. Could land as a quick win before the full extends feature.

    Happy to send a PR if there's appetite for it.

  5. clay-good
    added
    design-reviewNeeds product/design decision
    on Aug 27, 2026
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

    design-reviewNeeds product/design decision

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions