STANDARD MRK-1.0 SCHEMA mrk-1.0.schema.json LICENSE free to adopt · no email required
Knowledge both readers can trust.
An article is machine-ready when a machine can lift any section of it, alone, into an answer for a human, without guessing what it applies to, when it was true, or where it came from. Four clauses, one JSON Schema you can validate against today.
The key words MUST, MUST NOT, SHOULD and MAY in this document are to be interpreted as described in RFC 2119.
The standard ships as a schema.
# mrk-1.0.schema.json: root object. Each clause below contributes its fragment.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://machinereadyknowledge.com/mrk-1.0.schema.json",
"title": "MRK-1.0 - Machine-Ready Knowledge article front matter",
"type": "object",
"required": ["id", "title", "applies_to", "owner",
"lifecycle", "verified", "sections"]
}
the pattern / two readers, side by side
Four clauses make an article machine-ready.
Every section stands alone. Applicability is said out loud. Identifiers survive migrations. Freshness is a date, not a hope. A human attests what no schema can judge.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://machinereadyknowledge.com/mrk-1.0.schema.json", "title": "MRK-1.0 - Machine-Ready Knowledge article front matter", "type": "object", "required": ["id", "title", "applies_to", "owner", "lifecycle", "verified", "sections"] }
THE ESTATE-WIDE PATTERN: every page on this domain shows both readers; the panes above render the same served artifact
§1 / normative
§1Every section must stand alone.
A machine quotes sections, not pages. Each section must carry enough context to be safely lifted into an answer: no "as described above," no pronouns that resolve two headings back, no steps that silently depend on another section's setup.
- Each section MUST be safe to read in isolation; "as described above" is a violation
- Prerequisites MUST be stated inside the section that needs them
- The
self_containedflag is an attestation, set by a human at the curation gate; no schema can judge prose
# schema fragment: sections and their attestation
{"$defs": {"section": {
"type": "object",
"required": ["id", "self_contained"],
"properties": {
"id": {"type": "string",
"pattern": "^[a-z][a-z0-9-]*-[0-9]+#[a-z][a-z0-9-]*$"},
"self_contained": {"const": true,
"description": "Attested by a human curator, not inferred."}
}
}}}
# conforming instance
sections: - id: atk-2041#steps self_contained: true
§2 / normative
§2Say what it applies to. Out loud.
Humans infer applicability from where a page sits in the help centre. Machines don't get the folder tree. Plan, tier, region, version: if an answer is only true for some readers, the article must say so in a form a machine can filter on.
- Applicability MUST be stated as data, not implied by where the page sits
- "Applies to everyone" MUST be declared explicitly, never assumed
# schema fragment: applicability is required, structured, filterable
{"$defs": {"applicability": {
"type": "object",
"required": ["plan", "region"],
"properties": {
"plan": {"type": "array", "minItems": 1,
"items": {"type": "string"}},
"region": {"type": ["string", "array"]},
"version": {"type": "string"}
}
}}}
# conforming instance: a Starter-plan customer never sees this procedure
applies_to: plan: [scale, enterprise] region: all version: ">= 4.2"
§3 / normative
§3An answer you can cite is an answer you can audit.
Every article and every section carries an identifier that survives retitles, redesigns and migrations. Citations, gap logs and edit history all hang off these IDs; break them and you break the audit trail.
- An identifier MUST survive retitles, redesigns and migrations
- An identifier MUST NOT be reused after retirement
- The schema pins the format; stability over time is a process property; it's audited from your revision history, not from any single file
# schema fragment: identifier format
{"properties": {"id": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*-[0-9]+$",
"description": "Immutable once assigned. Never reused, never renamed."
}}}
# what a citation carries: every claim traces to a section and a version
citation: claim: "Keys revoked for a security event need owner approval." cite: atk-2041#steps version: 14
§4 / normative
§4Truth has a date on it.
A machine cannot smell staleness. Every article declares when it was last verified, who owns it, and where it sits in its lifecycle, so consumers can prefer fresh sources and flag decaying ones, instead of confidently serving last year's UI.
- Verification date and owner MUST be machine-readable
- Lifecycle state, current / superseded / retired, MUST be declared
- Consumers SHOULD downweight articles past their verification window and MAY refuse to answer from retired ones
# schema fragment: freshness fields
{"properties": {
"owner": {"type": "string"},
"verified": {"type": "string", "format": "date"},
"lifecycle": {"enum": ["current", "superseded", "retired"]},
"supersedes": {"type": "string",
"pattern": "^[a-z][a-z0-9-]*-[0-9]+$"}
}}
# conforming instance
owner: support-knowledge verified: 2026-07-30 lifecycle: current supersedes: atk-1988
Conformance
Score one article honestly.
Take your most-cited article and check it against the clauses. A typical corpus passes all four on 31% of articles at first audit; the rest is enumerable, prioritisable work.
0/4: most corpora start here. That's the point of measuring.
Templates that pass all four · the Toolkit The vocabulary layer · the essay The discipline behind it
# validate your corpus yourself, today: check-jsonschema is an existing OSS tool that accepts YAML instances
$ pipx install check-jsonschema $ check-jsonschema \ --schemafile https://machinereadyknowledge.com/mrk-1.0.schema.json \ kb/articles/*.yaml ok -- validation done # typical corpus, first audit: 31% of articles pass all four clauses
# the schema validates §2 and §4 mechanically, and §1's attestation flag. What it cannot judge (whether prose truly stands alone, whether IDs held stable across your history, coverage against your real ticket themes) is the human half of the audit. Run it with your own reviewers; the standard and the schema are free.
The maturity layer / MRK-1.1 → 2.0
The floor is not the ceiling.
The four clauses get an article to L1: contracted, liftable, safe to quote. Everything a knowledge graph can do lives above that line, and MRK-2.0 is the additive layer that climbs there without leaving Markdown. The Structure Graduation Ladder scores a corpus L0–L4 and names each article's next edit. Clause §R governs the reader: the assembler that turns articles into an answer. And the graph projection turns the corpus into queryable RDF with one JSON-LD context.
1.0 stays the served core and the honest starting bar. 2.0 is the path off it, one enumerable rung at a time.
The Structure Graduation Ladder Clause §R: retrieval The graph projection
# machine-readiness as a ladder, not a pass/fail
L1: contracted # the four clauses, today's bar L2: typed # + section roles, visibility L3: linked # + relations, concepts; projects to RDF L4: reasoned # SHACL-valid, deterministic SPARQL
# the 1.1 schema and the JSON-LD context are served here too: additive, backward-compatible, free to adopt.