specl-schema.yaml

---
#
# Some pre-defined meta-values provided for this schema (required).
#
identity:
  company: DevFactory
  version: 2.0

#
# All fields named `comment` simply provide a short explanatory paragraph for
# the context they are found in. They are useful for all who read the template
# file, but also for the tools that will generate the input UIs. These texts 
# will not persist in the final specs but are present during spec-writing as 
# comments or as placeholders in empty input fields.
# 
comment: >
  This document represents an L1 specification which describes in thorough 
  technical detail a single Milestone; it can consist of a single file, or
  multiple files, imported via referencing.

  Syntax is [SpecL Markdown](https://...) (i.e. Markdown + Gherkin).

#
# These are rendering options to be used when publishing a spec. However, the
# chosen rendering tool may choose to ignore or ovewrite them.
# 
# You can see how referencing to other nodes in the spec can work.
#
title: >
  L1 Spec: {/Metadata/Product Name} - {/Metadata/Release Name} - M{/Metadata/Milestone Number}

header: >
  L1 Spec: **Milestone {/Metadata/Milestone Number}**
  Release {/Metadata/Release Name}
  {/Metadata/Product Name}

#
# References can have fall-back values (in case referenced value is missing).
#
footer: >
  L1 schema version {schema: version} - Author: {/Metadata/Owner | "Unknown"} - {schema: company | "DF"}

#
# The entire specification is made of node, which can be nested. These define
# sections, input values and pretty much anything else.
#
schema:

  #
  # This is a node: a section definition.
  #
  Metadata:

    comment: >
      This is expected to be the first section of the Spec and it contains
      complete identification information.
   
    type: tree    # This section must be a tree object (just like a JS object). 
    strict: true  # I.e. authors can't add nodes other than the ones defined here (default).

    children:

      #
      # Sub-nodes of Metadata.
      #
      Product Name:
        type: string
        comment: "Short Capitalized Product Name."

        # Any node (even whole sections) can enforce validation rules.
        # These rules are interpreted based on the node's type.
        pattern: /^[a-zA-Z0-9 -]+$/
        min: 3
        max: 100

      Release Name:
        type:
          - number 
          - string
        comment: "Usually a version number, but can be a name also."
        pattern: /^[a-zA-Z0-9.-]+$/

      L2 Spec Link:
        type: string
        required: false # A node is required by default.
        comment: Link to the parent L2 Spec (if any).
        
        # Here's a pre-defined validation rule.
        pattern: {patterns: uri}

      Milestone Number:
        type: number
        comment: "A simple integer denoting the milestone count."
        min: 1

      Milestone Name:
        type: string
        comment: "A name for this milestone."
        pattern: {patterns: identifier}

      JIRA Ticket:
        type: string
        comment: "A ticket code, such as JIRA-123."
        pattern: "^[A-Z]+-[0-9]+$"
        
        # 
        # Custom JS validators can perform specialized checks.
        # 
        validators: 
          - {file(./validators/jira.js): isValidTicket}

      Owner:
        type: string
        comment: "spec-author@email.here"
        pattern: {patterns: email}

      Original:
        type: string
        comment: URI always pointing to the original spec.
        validators: 
          - {file(./validators/specs.js): isValidL1Uri}

  #
  # This section is a list of objects (between 1 and 100).
  #
  Glossary:
    comment: Complete this list to introduce any acronyms or jargon used in this spec.
    
    type: list
    min: 1
    max: 100

    item:
      type: tree
      strict: true
      children:
        Term:
          type: string
        Definition:
          type: string

    #
    # Use `samples` in any node to add sample values in the generated template.
    # These values must pass any validation rules defined for the node. Usually
    # the author is expected to eventually replace them (though not required).
    #
    samples:
      - 
        Term: ET1
        Definition: Example Term 1
      -
        Term: ET2
        Definition: Example Term 2

  #
  # This defines a variable list of capabilities (minimum 1).
  #
  Capabilities:
    comment: >
      Capabilities fall into a number of different Capability Types. This is expected
      to expand over time as our product management and engineering practices evolve. 
      Any TPM should feel empowered to define a new capability type and template and 
      add it to this repository.

    type: list
    min: 1
    max: 100

    item:
      type: tree
      children:

        Summary:
          type: string

        #
        # This node implements the `feature` type which is baeically Gherkin source 
        # code (possibly combined with Markdown syntax).
        #
        Definition:
          type: feature

          # For `feature` nodes, we could even use pre-defined Gherkin files
          # to enforce baselines for how the final text must look. The author's
          # content must comply to at least one of the baselines.
          baseline: 
            - {file(./features/api.feature)}
            - {file(./features/ui.feature)}
            - {file(./features/performance.feature)}
            - {file(./features/scalability.feature)}
            - {file(./features/report.feature)}
            - {file(./features/monitoring.feature)}
            - {file(./features/rollout.feature)}
            ...

    samples:
      - 
        Summary: UI enables login.
        Definition: >
          {file(./caps/login-screen.md)}