STANDARD MRK-1.0 DRAFT FOR COMMENT 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 toggle above shows the standard as a machine consumes it.

The key words MUST, MUST NOT, SHOULD and MAY in this document are to be interpreted as described in RFC 2119.

Read the clauses Have your corpus measured

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"]
}

§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_contained flag 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.

§1 Every section stands alone §2 Applicability stated as data §3 IDs stable across retitles and migrations §4 Verified date, owner and lifecycle declared

0/4 — most corpora start here. That's the point of measuring.

Have the whole corpus measured — AnswerEcon 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. That's AnswerEcon.

answerecon.com →