OKF concepts and metadata#

A concept is one normal Markdown file with a small YAML information block at the top.

You can create it with a form. You do not need to type YAML yourself.

Create your first concept#

Open the workspace.
Open Developer tools > Structure and OKF.
Select Create concept.
Set Template to Project documentation.
Enter Title: Release checklist.
Review the suggested path: concepts/release-checklist.md.
Enter One-line description: Checks the app before a public release.
Enter Tags: release, testing.
Leave Canonical resource empty.
Keep Status set to draft.
Leave Stale after empty.
Keep Generated by as devdesk/1.0.
Leave source and Stable ID fields empty.
Select Create.

Expected result: DevDesk creates a Markdown file with starter headings and portable frontmatter. The file also appears in workspace files and structure analysis.

If it does not appear, confirm that the relative path is inside the workspace and does not already exist.

What the form fields mean#

Field	Beginner meaning	Required by the form?
Template	Starter headings and suggested folder	Yes
Title	Human-readable name	Yes
Relative Markdown path	Location inside the workspace	Yes
One-line description	Short preview text	No
Tags	A few reusable categories	No
Canonical resource	Asset this concept describes	No
Status	`draft`, `stable`, or `deprecated`	Defaults to `draft`
Stale after	Date to review freshness	No
Generated by	Who or what created this version	Yes
Primary source resource	Real source supporting the concept	No
Primary source title	Readable source name	No
Stable ID	DevDesk-specific identity helper	No

Only the title and path need beginner input. Keep advanced optional fields empty until you understand why you need them.

Generated by actor format#

The app accepts:

human:baishalya for a person;
process:documentation-import for a known process;
devdesk/1.0 for a producer and version.

Do not use spaces. This field records creation metadata; it does not prove that the content was reviewed.

Minimal OKF concept#

The current validator requires parseable frontmatter and a non-empty type for a normal concept:

---
type: Reference
---
# Release checklist

Review the build before publishing.

The app form intentionally creates more useful metadata:

---
type: "Project Documentation"
title: "Release checklist"
description: "Checks the app before a public release."
tags:
  - "release"
  - "testing"
status: draft
generated:
  by: "devdesk/1.0"
  at: "2026-07-29T10:00:00.000Z"
---
# Overview

# Details

# Examples

The generated timestamp uses the actual creation time.

Template choices#

The current app offers:

Concept
API endpoint
API collection
Data model
Architecture decision
Runbook
Policy
Troubleshooting guide
Prompt
AI evaluation
Release note
Changelog entry
Project documentation
Attested computation

Choose Project documentation or Concept when unsure. A custom or unknown type is still treated as a generic concept; a known type name is not required for conformance.

Tags#

Enter comma-separated values in the form:

release, testing, windows

DevDesk saves them as a YAML list. Prefer a small consistent vocabulary.

Status and freshness#

draft: still being reviewed.
stable: currently approved for normal use.
deprecated: kept for history but should be replaced.
Stale after: a YYYY-MM-DD date after which the content needs review.

Stale does not mean false. It means “check this again.”

Resource and source are different#

Canonical resource identifies the asset described by the concept.
Primary source resource identifies evidence used to support the concept.

Do not invent either value. Leave it empty when no real resource exists.

Editing outside DevDesk#

The file remains ordinary Markdown. When editing YAML manually:

keep the opening and closing ---;
use spaces instead of tabs;
keep type non-empty;
save dates as YYYY-MM-DD;
refresh Structure and OKF after external edits.