PRD Requirements

Critical Requirement: All user stories in your PRD must use the PEDAL hybrid format, combining Connextra context ("As a user...") with Gherkin scenario structure. This is essential for deterministic parsing, automation, and unambiguous communication between product and engineering. See Hybrid User Story Format for full details, rationale, and canonical examples.

Quick Example

As a registered user, I want to reset my password, so that I can regain access if I forget it.

Scenario: Successful password reset
  Given I am on the password reset page
  And I have entered my registered email address
  When I submit the password reset form
  Then I receive an email with a reset link
  And my password is updated when I follow the link

Every user story must follow this structure. For more examples and a detailed explanation, see Hybrid User Story Format.

To ensure PEDAL can successfully process your Product Requirements Document (PRD) and generate a production-ready backend, your PRD must meet the following minimum requirements. This guide is for product owners, business analysts, and anyone responsible for authoring or submitting PRDs to the PEDAL pipeline.

Minimum PRD Requirements

A valid PRD for PEDAL must:

  • Be written in clear, structured Markdown (plain text is accepted, but Markdown is preferred for clarity).

  • Define all core entities (models/objects) with:

    • A unique name for each entity (e.g., User, Order)

    • A list of fields/properties for each entity, with:

      • Field name (e.g., email)

      • Field type (e.g., string, integer, boolean, date)

      • (Optional) Field constraints (e.g., required/optional, min/max, format)

  • Describe relationships between entities (e.g., User has many Orders)

  • Specify key business rules or validation requirements (e.g., "Email must be unique", "Order total must be positive")

  • Include at least one use case or user story (see above for required format)

PRD YAML Schema Reference

For the most precise and up-to-date requirements, you can view the target PRD YAML schema that PEDAL uses for validation:

This schema defines the exact structure, required fields, and allowed values for a valid PRD. Product owners and technical writers should refer to this file to ensure their PRD will be accepted by the pipeline and validation script.

Best Practices for Product Owners

  • Be explicit: Ambiguity leads to errors. Clearly state what each entity and field means.

  • Use consistent naming: Avoid synonyms or abbreviations unless defined.

  • List all required fields: Mark which fields are required vs. optional.

  • Describe relationships: Use phrases like "User has many Orders" or "Order belongs to User".

  • Include edge cases: If there are business rules (e.g., "A user cannot have more than 5 active orders"), state them clearly.

  • Avoid unstructured prose: PEDAL works best with lists, tables, and bullet points, not long paragraphs.

PRD Validation Script

PEDAL includes a validation script to check your PRD before running the full pipeline. This script:

  • Checks for required structure: Ensures all entities, fields, and relationships are defined.

  • Reports missing or ambiguous elements: If a field type is missing or a relationship is unclear, you'll get a clear error message.

  • Suggests corrections: Where possible, the script will suggest how to fix issues (e.g., "Field 'email' in 'User' is missing a type").

How to use:

node scripts/validate-prd.js --input path/to/your.prd.md

  • The script will print a summary of any issues found, or "Validation passed" if your PRD is ready.

Example PRD

For a reference PRD that meets all requirements, see:

This example demonstrates the ideal structure, level of detail, and formatting for a PEDAL-compatible PRD.

If you have questions or need help preparing your PRD, see the FAQ or contact the PEDAL team for support.

PreviousAdvanced UsageNextHybrid User Story Format

Last updated