4.1Product as Code Document

A document (or set of documents) that defines or describes product requirements, development tasks, and business context. A Product as Code definition uses and conforms to the Product as Code Specification.

4.2Hierarchical Structure

Product as Code follows a two-level hierarchy: Epics contain Tickets. Tickets represent atomic units of development work that map to single branches and pull requests. Tasks are lightweight implementation steps embedded within tickets as inline arrays. This structure provides natural scope boundaries while maintaining practical development workflow integration.

5.1Versions

The Product as Code Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.

The major.minor portion of the semver (for example 0.1) SHALL designate the PAC feature set. Typically, .patch versions address errors in this document, not the feature set. Tooling which supports PAC 0.1 SHOULD be compatible with all PAC 0.1.* versions.

A Product as Code document compatible with PAC 0.*.* contains a required apiVersion field which designates the semantic version of the PAC that it uses.

5.2Format

A Product as Code document that conforms to the Product as Code Specification is itself a structured object, which may be represented in either YAML or JSON format.

All field names in the specification are case sensitive.

The schema exposes two types of fields: Fixed fields, which have a declared name, and Optional fields, which may be included to provide additional context but are not required for basic compliance.

5.3Document Structure

A Product as Code document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, references between documents MUST use the unique identifier fields.

It is RECOMMENDED that Product as Code documents be named with descriptive names and appropriate file extensions:

• YAML format: epic-user-auth.yaml, ticket-login-form.yml
• JSON format: epic-user-auth.json, ticket-login-form.json

5.4Data Types

Primitive data types in PAC are based on YAML 1.2 supported types:

• string - UTF-8 text
• integer - Whole numbers
• boolean - true/false values
• array - Ordered list of values
• object - Key-value pairs

6.1Epic Object

An Epic represents a large feature set or initiative that provides business value. Epics contain multiple related tickets and serve as the highest level of organization in the Product as Code hierarchy.

6.2Ticket Object

A Ticket represents an atomic unit of development work that maps to a single git branch and pull request. Tickets belong to Epics and contain inline tasks that represent implementation steps within the unit of work.

6.3Task Object

A Task represents a lightweight implementation step within a Ticket. Tasks are embedded inline within Tickets and represent checkboxes or action items that comprise the unit of work.

6.4Pull Request Object

Information about the pull request associated with a Ticket’s implementation.

6.5Epic Reference Object

A reference to an Epic with both ID and optional human-readable name.

6.6Ticket Reference Object

A reference to a Ticket with both ID and optional human-readable name.

6.7Metadata Object

The Metadata Object contains identifying information and timestamps for all Product as Code objects.

7.1Epic Example (YAML)

apiVersion: productascode.org/v0.1.0
kind: Epic
metadata:
  id: epic-550e8400-e29b-41d4-a716-446655440000
  name: user-authentication
  created_at: 2025-01-15T10:30:00Z
  updated_at: 2025-01-15T10:30:00Z
  owner: product-team
  labels:
    priority: high
    quarter: Q1-2025
spec:
  description: "Complete user authentication system with signup, login, and password recovery"
  status: in-progress
  priority: high
  success_metrics:
    - "90% signup completion rate"
    - "< 2 second login time"
    - "Zero critical security vulnerabilities"
  tickets:
    - id: "login-form-ticket"
      name: "Login Form Implementation"
    - id: "signup-validation-ticket"
      name: "Signup Validation Logic"
  epics:
    - id: "password-recovery-epic"
      name: "Password Recovery System"
  owner: product-team
  related_to:
    - "admin-security-epic"
    - "user-profile-epic"

7.2Epic Example (JSON)

{
  "apiVersion": "productascode.org/v0.1.0",
  "kind": "Epic",
  "metadata": {
    "id": "epic-550e8400-e29b-41d4-a716-446655440000",
    "name": "user-authentication",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "owner": "product-team",
    "labels": {
      "priority": "high",
      "quarter": "Q1-2025"
    }
  },
  "spec": {
    "description": "Complete user authentication system with signup, login, and password recovery",
    "status": "in-progress",
    "priority": "high",
    "success_metrics": [
      "90% signup completion rate",
      "< 2 second login time",
      "Zero critical security vulnerabilities"
    ],
    "tickets": [
      {
        "id": "login-form-ticket",
        "name": "Login Form Implementation"
      },
      {
        "id": "signup-validation-ticket",
        "name": "Signup Validation Logic"
      }
    ],
    "epics": [
      {
        "id": "password-recovery-epic",
        "name": "Password Recovery System"
      }
    ],
    "owner": "product-team",
    "related_to": [
      "admin-security-epic",
      "user-profile-epic"
    ]
  }
}

7.3Ticket Example (YAML)

apiVersion: productascode.org/v0.1.0
kind: Ticket
metadata:
  id: 22
  name: "jwt-token-generation-validation"
  created_at: 2025-07-09T00:00:00Z
  updated_at: 2025-07-09T13:47:39Z
spec:
  description: |
    Implement comprehensive JWT token generation and validation utilities
    for the TIFY authentication system. This includes token creation,
    validation, refresh mechanisms, and proper error handling for
    expired or invalid tokens.
  type: "feature"
  parent: user-auth-epic
  status: "completed"
  priority: "high"
  branch_name: "22-jwt-token-generation-validation"
  assignee: "@mantcz"
  reviewer: "@mantcz"
  started_at: "2025-07-09T14:05:10Z"
  completed_at: "2025-07-09T14:47:39Z"
  estimate: "8h"

  acceptance_criteria:
    - "JWT token generation with configurable expiration times"
    - "Token validation with proper error handling"
    - "Refresh token mechanism for seamless user experience"
    - "Token blacklisting for logout functionality"
    - "Proper JWT claims validation (exp, iat, sub)"
    - "Environment-based JWT configuration"
    - "Comprehensive error handling for invalid/expired tokens"
    - "Token extraction from Authorization headers"
    - "Unit tests for all JWT utilities"
    - "Integration with existing authentication flow"

  tasks:
    - id: 1
      description: "Enhance JWT token generation with configurable options"
      done: true
      type: "feature"
      assignee: "@mantcz"
    - id: 2
      description: "Implement JWT token validation with proper error handling"
      done: true
      type: "feature"
      assignee: "@mantcz"
    - id: 3
      description: "Create refresh token mechanism"
      done: true
      type: "feature"
      assignee: "@mantcz"

  pull_request:
    url: "https://github.com/company/repo/pull/22"
    status: "merged"
    title: "Implement JWT token generation and validation"
    created_at: "2025-07-09T14:30:00Z"
    reviewers: ["@mantcz"]

  labels:
    - "authentication"
    - "jwt"
    - "security"
    - "middleware"

  depends_on:
    - "database-setup-ticket"
  related_to:
    - "user-registration-ticket"
    - "password-reset-ticket"

7.4Ticket Example (JSON)

{
  "apiVersion": "productascode.org/v0.1.0",
  "kind": "Ticket",
  "metadata": {
    "id": 22,
    "name": "jwt-token-generation-validation",
    "created_at": "2025-07-09T00:00:00Z",
    "updated_at": "2025-07-09T13:47:39Z"
  },
  "spec": {
    "description": "Implement comprehensive JWT token generation and validation utilities for the TIFY authentication system. This includes token creation, validation, refresh mechanisms, and proper error handling for expired or invalid tokens.",
    "type": "feature",
    "parent": "user-auth-epic",
    "status": "completed",
    "priority": "high",
    "branch_name": "22-jwt-token-generation-validation",
    "assignee": "@mantcz",
    "reviewer": "@mantcz",
    "started_at": "2025-07-09T14:05:10Z",
    "completed_at": "2025-07-09T14:47:39Z",
    "estimate": "8h",
    "acceptance_criteria": [
      "JWT token generation with configurable expiration times",
      "Token validation with proper error handling",
      "Refresh token mechanism for seamless user experience",
      "Token blacklisting for logout functionality",
      "Proper JWT claims validation (exp, iat, sub)",
      "Environment-based JWT configuration",
      "Comprehensive error handling for invalid/expired tokens",
      "Token extraction from Authorization headers",
      "Unit tests for all JWT utilities",
      "Integration with existing authentication flow"
    ],
    "tasks": [
      {
        "id": 1,
        "description": "Enhance JWT token generation with configurable options",
        "done": true,
        "type": "feature",
        "assignee": "@mantcz"
      },
      {
        "id": 2,
        "description": "Implement JWT token validation with proper error handling",
        "done": true,
        "type": "feature",
        "assignee": "@mantcz"
      },
      {
        "id": 3,
        "description": "Create refresh token mechanism",
        "done": true,
        "type": "feature",
        "assignee": "@mantcz"
      }
    ],
    "pull_request": {
      "url": "https://github.com/company/repo/pull/22",
      "status": "merged",
      "title": "Implement JWT token generation and validation",
      "created_at": "2025-07-09T14:30:00Z",
      "reviewers": ["@mantcz"]
    },
    "labels": [
      "authentication",
      "jwt",
      "security",
      "middleware"
    ],
    "depends_on": [
      "database-setup-ticket"
    ],
    "related_to": [
      "user-registration-ticket",
      "password-reset-ticket"
    ]
  }
}

7.5Task Example

Tasks are embedded inline within Tickets as shown in the Ticket example above. They represent lightweight implementation steps with simple fields:

tasks:
  - id: 1
    description: "Enhance JWT token generation with configurable options"
    done: true
    type: "feature"
    assignee: "@mantcz"
    estimate: "2h"
  - id: 2
    description: "Update environment variables for JWT configuration"
    done: false
    type: "chore"
    assignee: "@alice"
    estimate: "30min"