PLGen Syntax Specification

The open standard for
provenance declaration

Version: 1.0 Status: Draft Published: 2026-02-17 License: CC BY 4.0

Overview

PLGen is a plain-text syntax for declaring the provenance of AI-assisted content. It is human-readable, tool-parseable, and implementation-agnostic. Any tool — a CLI, a website, a browser extension — can read or write a valid .plgen file using this specification.

Think of it like Markdown: a simple set of rules that does useful work across many contexts without requiring special software to understand.

Design Principle PLGen is a disclosure format, not a quality certification. It makes no judgment about how much AI assistance is "too much." It simply asks: what happened, and who is accountable?

File Format

File extension: .plgen
Encoding: UTF-8
One field per line, format: key: value
Lines beginning with # are comments and are ignored
@provenance directive must appear on line 1

Fields

Field	Type	Description
`@provenance`	directive	Version declaration. Must be line 1.	Required
`author`	string	Full name of the human accountable for the content.	Required
`date`	YYYY-MM-DD	Date of completion or publication.	Required
`human`	integer 0–100	Percentage of human contribution. Must sum to 100 with `ai`.	Required
`ai`	integer 0–100	Percentage of AI contribution. Must sum to 100 with `human`.	Required
`tools`	string	AI tool(s) used. Comma-separated if multiple.	Optional
`shared-by`	string	Name of person republishing content they did not originally create.	Optional
`updated`	YYYY-MM-DD	Date of most recent substantive revision.	Optional
`note`	string	Single plain-language sentence describing the collaboration.	Optional
`ref`	URL or citation	Source referenced during creation. Repeatable for multiple sources.	Optional

Example

# PLGen v1.0 — provenance-label.org/spec
@provenance 1.0
author: Shelton Davis
date: 2026-02-17
human: 65
ai: 35
tools: Claude Sonnet 4.6
note: Concept and direction human. Draft and structure AI. Edited for voice.
ref: https://provenance-label.org/spec

Output Formats

Any valid implementation must support at minimum the --short and --long output formats. --json is recommended for tool integrations.

--short

Single-line badge. For inline use, footers, social posts.

--long

Full disclosure block. For articles, documentation, reports.

--json

Machine-readable export for tool integrations and APIs.

Short output

PL v1.0 | Shelton Davis | 2026-02-17 | Human 65% · AI 35% · Claude Sonnet 4.6

Long output

─────────────────────────────────────
PROVENANCE LABEL v1.0
─────────────────────────────────────
Author:   Shelton Davis
Date:     2026-02-17
Human:    65%
AI:       35%
Tools:    Claude Sonnet 4.6
Note:     Concept and direction human.
          Draft and structure AI.
          Edited for voice.
─────────────────────────────────────
provenance-label.org/spec

JSON output

{
  "plgen": "1.0",
  "author": "Shelton Davis",
  "date": "2026-02-17",
  "human": 65,
  "ai": 35,
  "tools": "Claude Sonnet 4.6",
  "note": "Concept and direction human. Draft and structure AI. Edited for voice."
}

Validation Rules

@provenance must appear on line 1 of the file
human + ai must equal exactly 100
date and updated must be valid YYYY-MM-DD format
Percentages must be integers between 0 and 100
note must be a single line (no newlines)
ref may appear multiple times for multiple sources

Registry (Coming)

Submitted labels will receive a permanent short ID — for example, PL-000312 — that can be embedded in content. Anyone can look up a label ID at provenance-label.org/r/PL-000312 to verify the original, timestamped disclosure.

How the registry works

1. Generate a .plgen file using any valid tool
2. Submit to provenance-label.org/submit
3. Receive a unique PL-ID for your label
4. Embed PL-ID in your content
5. Anyone can verify at provenance-label.org/r/[PL-ID]

Creator profiles: provenance-label.org/[author-name]
→ All labels by that author, in chronological order

Versioning

The @provenance directive specifies the spec version. Major version changes indicate breaking format changes. Minor version changes are backwards-compatible additions. Implementations should specify the version they support.

Building on PLGen

This specification is licensed CC BY 4.0. Anyone can build implementations — CLI tools, website generators, browser extensions, GitHub Actions, editor plugins — as long as they reference this spec. Implementation code is licensed MIT.

To propose changes to the spec, open an issue on the GitHub repository.