Dossiers
Dashboard Sign in Sign up

Metadata

Add structured information to your specifications

What is Metadata?

Metadata is structured information about your specifications. It appears at the top of each document as YAML frontmatter and is used to track important details like status, authors, and dates. 

---
created: 2025-01-15
status: Published
authors:
  - Jane Doe <jane@example.com>
---

# Your Specification Title

Your content here...

Standard Fields

Dossiers supports several standard metadata fields out of the box:

created

The date when the specification was created. If not provided, Dossiers will use the Git commit date of the file. 

created: 2025-01-15

Format: YYYY-MM-DD

status

The current status of the specification. Common values include:

  • Draft - Work in progress
  • Discussion - Open for feedback
  • Published - Approved and active
  • Completed - Implemented
  • Abandoned - No longer pursued
status: Published

updated

The date when the specification was last updated. If not provided, Dossiers will use the Git commit date. 

updated: 2025-02-20

authors

A list of people who wrote or contributed to the specification. Can be names only or names with email addresses. 

authors:
  - Jane Doe <jane@example.com>
  - John Smith

links

Related links such as tracking issues, pull requests, or design documents. 

links:
  - name: GitHub Issue
    url: https://github.com/org/repo/issues/123
  - name: Figma Design
    url: https://figma.com/file/...

Custom Metadata Fields

You can define custom metadata fields in your project configuration. See the Configuration guide for details on how to add custom fields like:

  • Target milestone or release version
  • Priority or severity
  • Component or team ownership
  • Estimated effort or complexity

Best Practices

Use Consistent Status Values

Define a standard set of status values for your project and stick to them. This makes it easier to filter and search for specifications in a particular state.

Include Contact Information

When listing authors, include email addresses so readers can reach out with questions or feedback.

Link to Related Resources

Use the links field to reference tracking issues, pull requests, design documents, or any other relevant resources. This helps readers understand the full context of the specification.

Keep Dates Updated

While Git history tracks all changes, explicitly updating the updated field for major revisions helps readers quickly see when significant changes were made.

Example Specification

Here's a complete example showing various metadata fields: 

---
created: 2025-01-15
updated: 2025-02-20
status: Published
authors:
  - Jane Doe <jane@example.com>
  - John Smith <john@example.com>
links:
  - name: Tracking Issue
    url: https://github.com/org/repo/issues/42
  - name: Implementation PR
    url: https://github.com/org/repo/pull/123
  - name: Figma Designs
    url: https://figma.com/file/abc123
---

# User Authentication System

## Problem

We need a secure authentication system that supports
multiple identity providers...

## Proposal

The authentication system will use OAuth 2.0 and support
Google, GitHub, and SAML providers...

Next Steps

Learn how to configure custom metadata fields and other project settings:

Configuration → Repository Structure →