Skip to main content
feature:
    name: frd-yaml
    description: A formal specification for compliant FRD.yaml files. A self-referential spec-for-the-spec.
    slug: FRD_YAML
    version: 1.0.0-beta.0

components:
    FILE:
        1: The file must begin with the `feature` top-level property, containing feature metadata
        2: The file may contain a `components` top-level property, with unique component keys
        3: The file may contain a `constraints` top-level property, with unique constraint keys
        4: A feature may not have multiple FRD files
        5: The filename may include the feature slug e.g. `MYSLUG_FRD.yaml`
        6: The file must be located as the direct child of a directory that matches the feature name e.g. `features/my-feature-name/FRD.yaml`

    FEATURE:
        name: Feature metadata
        description: Feature metadata is defined under the top-level `feature` key
        requirements:
            # feature.name
            1: Feature metadata must have a `name` field
            2-1: The `name` must be unique within the product
            2-2: The `name` must only contain lower-case chars, numbers, and dashes e.g. `my-feature-name`
            # feature.slug
            3: Feature metadata must have a `slug` field
            3-1: The `slug` must be unique within the product
            3-2: The `slug` must only contain upper-case chars, numbers, or underscores e.g. `MY_SLUG`
            # feature.description
            4: Feature metadata may have an optional `description` string
            # feature.version
            5: Feature metadata may have an optional `version` string
            5-1: If present, version must follow SemVer

    COMPONENT:
        name: Feature component
        description: Components are objects defined under the top-level `components` key.
        requirements:
            1: Each component must be defined under a component key
            2-1: Component key must only contain upper-case chars, numbers, or underscores e.g. `MY_COMPONENT`
            2-2: Must be unique within the feature; may not clash with another component key or another constraint key
            3: Each component must have a `requirements` field, containing a list of requirements.
            4: Each component can have an optional `name` string

    CONSTRAINT:
        name: Feature constraint
        description: |
            Constraints are objects defined under the top-level `constraints` property.
            The goal of the `constraints` property is to organize cross-cutting requirements, or criteria that don't fit within a single component.
        requirements:
            1: Each constraint must be defined under a constraint key
            2-1: Constraint key must only contain upper-case chars, numbers, or underscores e.g. `MY_CONSTRAINT`
            2-2: Must be unique within the feature; may not clash with another component key or another constraint key
            3: Each constraint must have a `requirements` field, containing a list of requirements.
            4: Each constraint can have an optional `name` string

    REQUIREMENT:
        name: Requirement and sub-requirement definitions
        description: |
            Requirements are numbered acceptance criteria that live under a component key or a constraint key.
            The goal of a requirement is to define a behavior or functionality.
        requirements:
            1: Requirement keys must be integer keys (e.g. `1:`, `2:`, `3:`)"
            2: Sub-requirement must associate to a parent requirement's number, using integer-dash keys (e.g., `1-1`, `1-2`)
            4: Sub-requirement keys must never include `-0` as the parent requirement is implicitly the 0th item.
            5: Requirements may be written as any yaml compatible string, including multi-line blocks with markdown, gherkin, etc.
            6: Requirement definitions must describe functional and objective criteria that can be verified as acceptable or not.
            7: Requirements and sub-requirements can be defined as either key-string pairs or key-object pairs
            8: When defined as an object, the object must contain a `requirement` property with the requirement definition string
            8-1: The object may contain a `note` property with a string value
            8-2: The object may contain a `deprecated` property with a boolean value
            8-3: The object may contain a `replaced-by` property with a list of ACID strings
            9: Requirement notes may alternatively be defined in-line and attached to a parent requirement or subrequirement the -note suffix, (e.g. `1-note`, `2-1-note`)

    ACID:
        name: Requirement ID references / Acceptance Criteria IDs (ACIDs)
        requirements:
            1: A requirement can be referenced anywhere in the product via its unique ACID
            2: ACIDs follow the format `<FEATURE_SLUG>.<KEY>.<ID>` for example `FEAT.MY_COMPONENT.1-1` or `FEAT.CONSTRAINT.2`