A minimal semantic convention for signaling freshness, stewardship, and review posture over time.
Short convention name: .freshness.yml
Freshness Semantics Specification is an experimental, implementation-light metadata convention for describing the lifecycle posture of accessible artifacts. It is designed to help humans, infrastructure, and AI systems reason about whether an artifact is living, aging, stale, expired, archived, or abandoned without confusing freshness with correctness.
This specification is experimental and not peer reviewed at the time of initial release.
Freshness without stewardship can describe age, but it cannot describe accountability.
Repositories, document stores, knowledge bases, and retrieval systems accumulate artifacts that remain accessible long after their original context changes. Those artifacts may still be useful, but their review posture can become unclear. .freshness.yml provides a small, machine-readable and human-readable signaling layer that can travel with artifacts whenever possible.
The convention is intentionally small. It does not define a compliance program, governance program, centralized metadata platform, workflow product, risk engine, authority model, canonicality model, provenance graph, workflow orchestration system, or document management system.
Freshness is not correctness. A fresh artifact can be wrong, and a stale artifact can remain valid.
The purpose of this specification is to make review posture explicit. It gives readers and systems a deterministic way to ask: when was this artifact reviewed, who stewards it, when should it be reviewed again, and how should stale or expired posture affect retrieval and interpretation?
Freshness metadata should reduce ambiguity, not create process weight.
Freshness Semantics defines review posture and stewardship signals. It does not define truth, authority, or compliance.
- Freshness is NOT correctness.
- Stale does NOT mean wrong.
- Expired does NOT imply deletion.
- Abandoned does NOT imply useless.
- Freshness is a review posture.
- Freshness includes stewardship, not only dates.
- Accessible stale artifacts can carry operational and AI retrieval risk.
- Semantic decay is different from deletion.
- Metadata should travel with artifacts whenever possible.
- Simplicity is more important than completeness.
- The specification should remain intentionally small.
freshness:
spec: freshness.v0.1
attachment: sidecar
subject:
path: docs/operational-runbook.md
type: document
lifecycle:
mode: living
status: aging
reviewed_at: 2026-05-25
review_after: 2026-08-25
stewardship:
owner:
type: team
id: sd-platform
steward:
type: agent
id: docs-review-bot
accountable:
type: domain
id: operations
confidence:
level: mediumThis says the artifact is living, still usable, entering an aging posture, stewarded by an automated review agent, accountable to an operations domain, and should be reviewed after 2026-08-25. It does not say the artifact is correct.
Stewardship is part of freshness because review posture depends on who or what still stands behind the artifact.
A steward MAY be an individual, team, domain, organization, role, automated agent, service account, AI-assisted workflow, or explicitly unassigned. none is valid when no steward is known, but it should be treated as a stewardship gap signal.
freshness:
lifecycle:
mode: living
status: aging
reviewed_at: 2026-05-25
review_after: 2026-08-25
stewardship:
owner:
type: team
id: sd-platform
steward:
type: agent
id: docs-review-bot
accountable:
type: domain
id: security
contact: security@simplestdata.comThe intent is accountability visibility, not approval workflow, role matrices, or organizational hierarchy.
Use .freshness.yml metadata where review posture matters and ordinary file timestamps are not enough.
There is no package to install and no central service to adopt. To use the convention in a repository, add one of these:
- embedded frontmatter in a Markdown artifact
- a sidecar file such as
artifact-name.freshness.yml - a repo-level index such as
.freshness.yml
Optional validation can use schema/freshness.schema.json directly or the small reference tool in tools/validate-freshness.py.
For Markdown and other editable text formats, embed freshness metadata in frontmatter.
---
freshness:
spec: freshness.v0.1
attachment:
model: embedded
lifecycle:
mode: living
status: current
reviewed_at: 2026-05-25
review_after: 2026-08-25
stewardship:
steward:
type: team
id: docs-maintainers
confidence:
level: high
---
# RunbookFor binary or non-editable artifacts, place metadata beside the artifact.
network-diagram.pdf
network-diagram.freshness.yml
For repo-level defaults or broad artifact groups, maintain an index file.
.freshness.yml
repo-index.freshness.yml
Index metadata should not hide artifact-specific warnings. Use it for defaults, grouping, and review posture that genuinely applies across a set of artifacts.
This repository includes a small validator example:
python3 tools/validate-freshness.py examples/*.freshness.yml examples/markdown-frontmatter.mdThe validator parses YAML, validates the document against schema/freshness.schema.json, and emits warnings for stale, expired, abandoned, or overdue review posture. It exits non-zero on invalid schema. Use --fail-on-warning if warnings should fail a CI job.
The tool is intentionally small. It is an example implementation, not a required runtime or authoritative platform.
| Model | Best for | Tradeoff |
|---|---|---|
| Embedded | Markdown, frontmatter-capable text, living docs | Metadata travels inside the artifact, but may not work for binary formats. |
| Sidecar | PDFs, images, exports, generated artifacts, non-editable files | Keeps metadata near the artifact, but association depends on naming or path conventions. |
| Index | Repo-level defaults, artifact groups, broad inventories | Efficient for groups, but can drift from individual artifacts if overused. |
Preferred defaults:
- Use embedded metadata for Markdown/frontmatter documents.
- Use sidecar metadata for binary or non-editable artifacts.
- Use index metadata for repository-level defaults and broad inventories.
AI retrieval systems can treat accessible artifacts as available context even when their review posture is unclear. That can create stale retrieval risk: old artifacts may be synthesized into answers with more authority than they deserve.
Freshness metadata can help AI systems and AI-assisted workflows:
- identify stale, expired, abandoned, or unassigned artifacts before retrieval
- reduce synthetic authority by surfacing review posture
- distinguish semantic decay from deletion
- support repository hygiene by finding overdue reviews
- weight retrieved context more carefully
- ask for human review when metadata says caution is appropriate
Freshness metadata should not be treated as proof of correctness. It is a signal for interpretation and review.
Freshness is not data classification and does not replace sensitivity labels, retention policies, classification frameworks, or governance controls.
Freshness metadata can complement classification programs by exposing stale accessible artifacts, identifying overdue review posture, improving repository and information architecture hygiene, and helping AI-assisted retrieval systems disclose stale context.
See docs/data-classification.md and examples/data-classification.freshness.yml.
README.md project overview
SPEC.md lightweight specification
CONTRIBUTING.md contribution guidance
CODE_OF_CONDUCT.md community expectations
SECURITY.md vulnerability reporting guidance
LICENSE Apache-2.0 license
NOTICE project notice
CHANGELOG.md release notes
schema/freshness.schema.json JSON Schema Draft 2020-12 schema
examples/ example metadata attachments
ci/ CI snippets for common platforms
tools/validate-freshness.py simple validation tool
docs/ supporting design notes
docs/data-classification.md data classification integration guidance
.github/ issue and pull request templates
Contributions are welcome. This is an experimental working specification, so the highest-value contributions improve clarity, interoperability, examples, and precise semantics.
Please avoid unnecessary ontology expansion. The specification should remain minimal, deterministic, platform-agnostic, and implementation-light.
See CONTRIBUTING.md for details.
This project is an early-stage semantic specification. It is not peer reviewed at initial release. It should not be treated as legal, compliance, security, or governance advice.
Use it as a small interoperable convention for making freshness and stewardship signals explicit. It provides implementation guidance only. It is not guaranteed to improve AI outcomes, though it may be useful for AI retrieval hygiene, repository hygiene, and governance support.
The specification intentionally avoids defining authority, canonicality, provenance graphs, or workflow orchestration.
Project contacts are placeholders for the initial public release:
- Personal GitHub:
TODO: https://github.com/<your-handle> - Simplest Data GitHub org:
TODO: https://github.com/<simplest-data-org> - Maintainer contact:
TODO: maintainer@example.com
Apache License 2.0. See LICENSE and NOTICE.