WinMedia logoWinMedia
Normative SpecificationFrozen Public Contract (v0.1)CC BY 4.0 / MIT

Machine Edition Specification v0.1

The canonical technical specification governing the structure, discrete meaning units, multi-resolution hierarchies, schema contracts, and referential provenance invariants of conformant Machine Edition packages.

Status: Frozen Public Contract (v0.1)Classification: Normative SpecificationCanonical URI: https://winmedia.com/machine-editions/specification/v0.1

This document is the normative conformance authority. For architecture overviews, comparative matrices, and empirical research, visit the Machine Edition Reference Headquarters.

Developer Kit Repository →Reference Headquarters →Download Reference Specimen (.zip) →

Section 01

1. Purpose and Scope

A Machine Edition is a structured publication package engineered explicitly for programmatic retrieval, direct inspection, automated validation, deterministic transformation, and governed use by software systems and artificial intelligence agents.

Conventional digital publications (such as PDFs and standard EPUBs) optimize for visual rendering and linear human reading. While language models can ingest raw text extracted from human editions, doing so introduces structural ambiguity, lost provenance, ungrounded chunking boundaries, and unreliable reference resolution.

A Machine Edition provides an explicit, machine-readable contract representing knowledge units, hierarchical relations, semantic boundaries, definitions, provenance links, and cryptographic integrity verifications.

1.1 Non-Goals and Distinctions

A Machine Edition is explicitly distinct from:

  • PDFs / PostScript files: Not fixed-layout visual rendering streams; contains explicit discrete data records without presentation markup noise.
  • EPUBs / MOBI files: Not document-flow human reader packages; decomposes text into addressable semantic units rather than human reading chapters.
  • Arbitrary RAG Chunks: Not arbitrary fixed-character or sliding-window string fragments; units represent coherent semantic assertions bounded by explicit domain scope.
  • Generic Knowledge Graphs: Not open-world arbitrary triples; strictly bound to source publication provenance, resolution hierarchies, and verified claim boundaries.

Human Edition

Sustained narrative flow, interpretation, visual pacing, and contextual nuance for human contemplation and study.

Machine Edition

Governed machine retrieval, verifiable provenance, explicit assertion bounding, and computable multi-resolution structure.

Important Boundary: The Machine Edition specification defines the structure, conformance, and validation contract of the resulting artifact. It does not govern or require specific proprietary extraction algorithms, internal editorial adjudication pipelines, or generation machinery.

Section 02

2. Normative Terminology

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

Package

The top-level container (directory, archive, or bundle) containing the manifest, data records, schemas, and human entrypoint.

Manifest (manifest.json)

The normative entrypoint file declaring package identity, versioning, format capabilities, entrypoint mappings, and license terms.

Meaning Unit (meaning-units.jsonl)

An atomic addressable assertion or concept unit possessing a unique identifier, resolution level, claim text, and provenance link.

Resolution Level (L0–L4)

A discrete granularity tier indicating depth of disclosure: L0 (core assertion), L1 (executive summary), L2 (sectional synthesis), L3 (detailed claims), L4 (granular evidence).

Definition (definitions.jsonl)

An explicit term binding mapping a domain term to its precise definition within the publication scope.

Boundary (boundaries.jsonl)

A negative or scope-limiting assertion defining what the publication or concept does not claim or cover.

Relationship (relationships.jsonl)

A typed directional or symmetric link between two entities (e.g., derives_from, clarifies, depends_on, refutes).

Provenance (provenance.jsonl)

A verifiable link binding a meaning unit, definition, or claim back to its source publication, chapter, page, URL, or editorial origin.

Human Entrypoint (full-preview.md)

A human-readable markdown representation of the package content facilitating direct human inspection.

Section 03

3. Package Structure and Organization

A conformant Machine Edition v0.1 package MUST adhere to the standardized file layout and encoding rules.

<package-root>/
├── manifest.json            [REQUIRED]  Normative package manifest
├── meaning-units.jsonl      [REQUIRED]  Discrete meaning unit records
├── definitions.jsonl        [OPTIONAL]  Domain term definitions
├── boundaries.jsonl         [OPTIONAL]  Negative boundaries and scope limits
├── relationships.jsonl      [OPTIONAL]  Inter-unit semantic relationships
├── provenance.jsonl         [REQUIRED]  Source citation and provenance records
├── full-preview.md          [REQUIRED]  Human-readable markdown entrypoint
├── LICENSE.txt              [REQUIRED]  Usage license and rights metadata
├── CHANGELOG.md             [OPTIONAL]  Version history
└── schemas/                 [OPTIONAL]  Package-bundled validation schemas
    ├── manifest.schema.json
    └── meaning-unit.schema.json

3.1 File Formats

  • Metadata files (manifest.json) MUST be valid JSON (RFC 8259) encoded in UTF-8.
  • Record files (*.jsonl) MUST be valid newline-delimited JSON (NDJSON) where each line is a single valid UTF-8 JSON object terminated by \n or \r\n. Empty lines are ignored.
  • Narrative entrypoints (full-preview.md) MUST be valid CommonMark / Markdown encoded in UTF-8.

Section 04

4. Identity, Versioning, and Source Binding

Requirements for global package identification, semantic version transitions, and verifiable lineage back to authoritative human editions.

4.1 Package Identity

Every package MUST define a unique package_id in reverse-domain notation (e.g. winmedia.srow.machine-edition.preview).

4.2 Semantic Versioning

Package version MUST follow Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH) for schema changes, additions, and errata.

4.3 Source Binding

Every meaning unit MUST bind to an identifiable record in provenance.jsonl through the provenance_id attribute.

Section 05

5. Schema Specifications

Formal JSON Schema Draft 2020-12 definitions for Manifest, Meaning Units, and Provenance records.

5.1 Package Manifest Schema (manifest.schema.json)

JSON Schema 2020-12
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://winmedia.com/schemas/machine-edition/v0.1/manifest.schema.json",
  "title": "Machine Edition Manifest Schema v0.1",
  "type": "object",
  "required": [
    "package_id",
    "title",
    "version",
    "status",
    "scope",
    "formats",
    "license",
    "human_readable_entrypoint",
    "provenance_file"
  ],
  "properties": {
    "package_id": {
      "type": "string",
      "pattern": "^[a-z0-9]+(\\.[a-z0-9\\-_]+)+$"
    },
    "title": { "type": "string", "minLength": 1 },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$"
    },
    "status": {
      "type": "string",
      "enum": ["developer_preview", "release_candidate", "stable", "deprecated"]
    },
    "scope": { "type": "string", "minLength": 1 },
    "formats": {
      "type": "array",
      "minItems": 1,
      "items": { "type": "string" }
    },
    "resolution_levels": {
      "type": "array",
      "items": { "type": "string", "enum": ["L0", "L1", "L2", "L3", "L4"] }
    },
    "license": { "type": "string", "minLength": 1 },
    "human_readable_entrypoint": { "type": "string", "minLength": 1 },
    "provenance_file": { "type": "string", "minLength": 1 },
    "integrity": {
      "type": "object",
      "description": "Optional map of relative filepaths to SHA-256 hashes",
      "additionalProperties": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
    }
  },
  "additionalProperties": true
}

5.2 Meaning Unit Schema (meaning-unit.schema.json)

JSON Schema 2020-12
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://winmedia.com/schemas/machine-edition/v0.1/meaning-unit.schema.json",
  "title": "Machine Edition Meaning Unit Schema v0.1",
  "type": "object",
  "required": [
    "id",
    "record_type",
    "version",
    "resolution_level",
    "title",
    "claim",
    "provenance_id",
    "scope"
  ],
  "properties": {
    "id": { "type": "string", "pattern": "^[a-z0-9\\-_.]+$" },
    "record_type": { "const": "meaning_unit" },
    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
    "resolution_level": { "type": "string", "enum": ["L0", "L1", "L2", "L3", "L4"] },
    "title": { "type": "string", "minLength": 1 },
    "claim": { "type": "string", "minLength": 1 },
    "provenance_id": { "type": "string", "minLength": 1 },
    "scope": { "type": "string", "minLength": 1 }
  },
  "additionalProperties": false
}

5.3 Provenance Record Schema (provenance.schema.json)

JSON Schema 2020-12
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://winmedia.com/schemas/machine-edition/v0.1/provenance.schema.json",
  "title": "Machine Edition Provenance Record Schema v0.1",
  "type": "object",
  "required": [
    "id",
    "record_type",
    "source_title",
    "source_url",
    "source_scope"
  ],
  "properties": {
    "id": { "type": "string", "pattern": "^[a-z0-9\\-_.]+$" },
    "record_type": { "const": "provenance" },
    "source_title": { "type": "string", "minLength": 1 },
    "source_url": { "type": "string", "format": "uri" },
    "source_scope": { "type": "string", "minLength": 1 },
    "retrieved_for_preview": { "type": "string" },
    "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
  },
  "additionalProperties": true
}

Section 06

6. Capability and Integrity Declarations

Explicit functional capability declarations and cryptographic checksum mappings in the manifest.

6.1 Capability Declarations

The manifest.json declares available formats (e.g. ["markdown", "jsonl", "json-schema"]) and available resolution levels (["L0","L1","L2","L3","L4"]).

6.2 Cryptographic Integrity

Packages MAY declare an integrity object in manifest.json listing relative file paths and hexadecimal SHA-256 digests. Consumers and validators verify file contents match.

Section 07

7. Rights, Licensing, and Usage Metadata

A Machine Edition is subject to explicit licensing terms declared in the referenced LICENSE.txt.

Evaluation and Inspection: Non-commercial evaluation, schema inspection, and automated testing are permitted within the declared specimen license.

Restricted Operations (Unless Explicitly Licensed):

  • Bulk ingestion into open foundation model training pipelines without attribution or license agreement.
  • Re-distribution of derivative data representations without maintaining provenance links.
  • Commercial API re-hosting without authorization.

Section 08

8. Extension Points

Rules for extending packages with domain-specific record types while preserving interoperability.

1. Custom JSONL Types

Additional *.jsonl files (e.g. methodologies.jsonl, citations.jsonl) MAY be added to the package root.

2. Manifest Extension

manifest.json permits extension properties via additionalProperties: true, without overwriting standard fields.

3. Invariance Rule

Extensions MUST NOT weaken, invalidate, or contradict required normative fields or integrity invariants.

Section 09

9. Conformance Checklist (C1–C7)

To achieve conformance with Machine Edition Specification v0.1, a package MUST satisfy all seven criteria.

C1

Manifest Presence

manifest.json exists at root and validates against manifest.schema.json.

C2

Required Files

manifest.json, meaning-units.jsonl, provenance.jsonl, full-preview.md, and LICENSE.txt are present.

C3

Valid JSONL

All *.jsonl files contain valid newline-delimited UTF-8 JSON.

C4

Meaning Unit Validation

All records in meaning-units.jsonl validate against meaning-unit.schema.json.

C5

Referential Integrity

Every provenance_id referenced in any record exists in provenance.jsonl.

C6

Human Entrypoint Linkage

The file declared in manifest.json under human_readable_entrypoint exists.

C7

License Alignment

The license file declared in manifest.json exists and is readable.

Section 10

10. Worked Example & Explicit Non-Examples

Concrete normative records and boundary definitions of what constitutes a conformant Machine Edition.

10.1 Worked Example: Meaning Unit & Provenance Pair

In meaning-units.jsonl:

{"id":"srow.preview.mu.001","record_type":"meaning_unit","version":"0.1.0","resolution_level":"L1","title":"Structure is a form of reader respect","claim":"Explicit structural hierarchy reduces cognitive friction for both human readers and automated inference agents.","provenance_id":"prov.public-srow-framework","scope":"core principle"}

In provenance.jsonl:

{"id":"prov.public-srow-framework","record_type":"provenance","source_title":"SROW — Structured Resolution-Oriented Writing","source_url":"https://winmedia.com/frameworks/srow","source_scope":"public WinMedia framework page","retrieved_for_preview":"2026-07-26"}

10.2 Explicit Non-Examples

1. Raw OCR / Scanned Dump

Unstructured {"page_1": "raw string..."} is NOT conformant (lacks atomic units, resolution tiers, typed records, and provenance).

2. Arbitrary Text Chunks

500-token chunks with no package_id, resolution level, or schema definition are NOT conformant.

3. Generic Unbound RDF Dump

Unanchored triple dumps with no link to human readable entrypoints, no manifest, and no package-level versioning are NOT conformant.

Section 11

11. Citation Metadata

When citing this specification in scholarly publications, technical documentation, or implementation ledgers.

@misc{winmedia2026machineedition,
  author = {Lynn Media},
  title = {Machine Edition Specification v0.1},
  year = {2026},
  url = {https://winmedia.com/machine-editions/specification/v0.1},
  note = {Frozen Public Contract}
}