Spec: add recommended provenance fields — author, publisher, published, license

OKF's recommended fields cover the artifact well — `type`, `title`, `description`, `resource`, `tags`, `timestamp`. But once an OKF document is *published* — handed to someone outside the producing system — three things consumers routinely need have no home in the spec:

- **who is responsible for it** (author), and **who published it** (publisher — often a different party),
- **when it was published** (distinct from `timestamp`, which the spec defines as *last meaningful modification*), and
- **under what license** it may be reused.

These are exactly the things the established metadata vocabularies standardized for this purpose — **Dublin Core / DCMI Terms** (`creator`, `publisher`, `issued`, `license`) and **Schema.org** (`author`, `publisher`, `datePublished`, `license`). OKF doesn't need to import a vocabulary — just to name a few recommended keys so producers and consumers spell them the same way instead of each inventing `lic` vs `license` vs `rights`.

**Why it matters for OKF specifically:** OKF's pitch is a portable format that travels between tools and vendors. The moment a bundle travels, provenance and license travel with it — or they're lost. A reader who finds an OKF file should be able to tell, from the frontmatter alone, who stands behind it and whether they may reuse it. Today they can't, and unknown-key tolerance means everyone will solve it differently.

**Scope — the descriptive layer, not the trust layer.** This is deliberately narrower than, and complementary to, the verifiable-provenance question raised in #47 by @WGlynn (signing, tamper-evidence, non-repudiable authorship). What's proposed here is plain bibliographic metadata — an *unverified claim* of who authored and published a document, when, and under what license. The two compose cleanly: these fields state what a document claims about itself; a trust layer like #47's would let a consumer *verify* those claims. Naming the descriptive keys doesn't presuppose or block the trust work — it just stops everyone from inventing their own spelling of "author" in the meantime.

### Proposed addition — recommended (not required) fields

```yaml
author: Ada Lovelace # party responsible for authorship (cf. dc:creator / schema:author)
author_email: ada@example.com
author_url: https://example.com
publisher: Example Org # party responsible for publishing (cf. dc:publisher)
publisher_url: https://example.org
published: 2026-01-01T00:00:00Z # publication datetime; distinct from `timestamp` (cf. dcterms:issued / schema:datePublished)
license: CC-BY-4.0 # SPDX license identifier (cf. dcterms:license)
license_url: https://creativecommons.org/licenses/by/4.0/
```

Consistent with OKF's existing stance: all of these are **recommended, not required**; consumers already must preserve them as unknown keys, and would simply gain a shared spelling. `type` remains the only mandatory field, and every field degrades gracefully if omitted. This is an additive, backward-compatible change — in the same spirit as the optional-fields proposal in #49 by @yzfly.

### Flat scalars vs. nested objects — and why I'd suggest flat

The obvious alternative is to model author/publisher as nested objects:

```yaml
# nested — NOT what I'm proposing, shown for comparison
author:
name: Ada Lovelace
email: ada@example.com
url: https://example.com
```

**Nested is, in the abstract, the better-modeled choice** — an author really is a composite of name + contact + link, nesting groups those cleanly, it extends without crowding the top-level namespace, and it mirrors the Schema.org/JSON-LD object model. If OKF were primarily consumed by code that deserializes frontmatter into typed structures, I'd argue for nesting.

**But I think flat scalars fit OKF better, for one decisive reason: OKF's adoption path is imitation.** The spec's whole ethos is "small enough to hold in your head," all-scalar frontmatter, unknown-keys-are-fine — a format people adopt by *eyeballing someone else's file and copying the pattern into their own*. In that world:

- **Flat scalars are far harder to get wrong by hand.** YAML indentation is the number-one hand-authoring footgun; a casual author who copies a flat example and fills in their own values produces valid frontmatter, while the same author copying a nested block frequently produces broken YAML.
- **Flat matches what OKF already is.** Every current recommended field is a top-level scalar. Introducing the format's first nested objects raises the floor for marginal structural gain.
- **Graceful degradation is per-field.** Omit `author_url` and nothing else cares — no half-empty object to reason about.

The cost of flat is a slightly larger top-level namespace and a by-convention (prefix) rather than by-structure relationship between `author` and `author_email`. For a human-eyeballed, copy-the-pattern format, that's the right trade. (A middle path, if the maintainers prefer: allow `author` to be *either* a bare string or an object — but that pushes complexity onto consumers, so I'd lean against it.)

### Sub-decisions for the maintainers

1. **Word separator for keys** — recommend underscore. OKF has no multi-word keys yet, so this proposal sets the precedent, and I'd suggest setting it to **underscore** (`author_email`). The concrete reason: underscore keys map to valid identifiers in essentially every language and templating engine (`data.author_email`, `{{ author_email }}`), whereas hyphen keys (`author-email`) must be quoted or bracketed because `-` parses as subtraction — a recurring friction for any consumer that binds frontmatter to variables. Underscore/snake_case is also the prevailing convention for multi-word frontmatter keys in the markdown ecosystem. Hyphens read a touch more naturally, but the programmatic-access cost outweighs it for a format meant to be machine-consumed. Whatever the choice, the spec should **pick one and apply it consistently**.
2. **`license` form** — recommend an **SPDX identifier** string (`CC-BY-4.0`, `MIT`, `MPL-2.0`)? It's the de-facto machine-readable standard and sidesteps free-text license ambiguity.
3. **A SHOULD-list of licenses?** — for a knowledge format it may help to *recommend* a small set appropriate to open knowledge and code — e.g. `CC0-1.0`, `CC-BY-4.0` (knowledge/prose) and `MIT`, `BSD-3-Clause`, `MPL-2.0` (code-bearing) — while allowing any SPDX id. Lowers the "which license?" barrier without constraining anyone.
4. **Whether the party fields may repeat.** Some works have more than one author (and, less often, more than one publisher), so the spec should say whether `author` / `publisher` (and their paired `_email` / `_url`) are single- or multi-valued. Three options to choose among:

1. **Single-valued** — each of these keys SHOULD carry exactly one value.
2. **Repeated keys** — a document MAY include the same key more than once, one value per occurrence. Note this sits awkwardly with the YAML substrate: YAML disallows duplicate mapping keys, and parsers variously reject the document or silently keep only the last value.
3. **Delimited scalar** — a single key MAY carry multiple values separated by a delimiter (comma or other). Three drawbacks worth weighing: it invites **parsing inconsistency** — some consumers will split on the delimiter, others won't — a multi-value field is **visually indistinguishable from a single value**, so you can't tell the convention is even in play by looking at one document, and **the delimiter collides with the data** — personal and organization names routinely contain commas ("Smith, Alice"; "Example, Inc.").

Consumers need one rule to parse against, so it's worth the spec picking one explicitly.
5. **Relationship to `timestamp`** — worth one sentence clarifying `timestamp` = last modified vs. `published` = issued, since the two are easy to conflate.

Happy to send this as a PR against `SPEC.md` (recommended-fields subsection) if the direction's agreeable — I'll sign the CLA. Either way, thanks again for OKF.

---
*Drafted by AI (Claude Code, Opus 4.8) under the direction of Peter Kaminski, who has reviewed it and takes full responsibility for its content.*