# The Product In Plain Language

## The Problem

Useful knowledge is often scattered across Markdown notes, catalogue exports,
API descriptions, spreadsheets, official feeds and specialist websites. A
person can open those files one at a time, but it is difficult to answer
questions across them:

- What records exist?
- Which organisation published them?
- What topics and formats do they cover?
- How are two records related?
- Where did a claim come from?
- Is a value `official`, `normalized`, `inferred` or generated by a model?
- Can another person open the same result and see the same evidence?

OKF Explorer turns a published collection into a navigable, searchable
evidence space. It runs in a web browser and can load a compatible collection
from a public URL.

## Three Things With Similar Names

The terms below describe different parts of the system.

### OKF

Open Knowledge Format, or OKF, is a way to package human-readable knowledge so
software can also identify records and links. In the repository's original
small corpus, the source material is ordinary Markdown with metadata at the
top of each file.

OKF is the content and interchange side of the project. It is not the visual
application.

### An OKF Bundle Or Pack

A bundle is a published collection that the Explorer can load. A small bundle
can contain its records and relationships in one JSON file. A large pack uses
a small descriptor that points to separate search indexes, record chunks,
relationships and analysis files.

“Pack,” “bundle” and “corpus” appear frequently:

- a **record** is one described thing;
- a **corpus** is the collection of records being studied;
- a **bundle** or **pack** is a publication of that corpus and its supporting
  indexes and metadata.

### OKF Explorer

The Explorer is the browser interface. It lets a person search, filter, select
and inspect records through several coordinated views. It does not own the
truth of the source material. It reads what a pack publishes and explains
limits where possible.

## The People In The System

A single person can perform several of these roles, but keeping the roles
separate makes responsibilities clearer.

| Role | Main concern |
|---|---|
| Source publisher | The official or originating material |
| Pack author | Selecting, normalising and documenting source material |
| Pack builder | Producing machine-readable records and indexes |
| Explorer maintainer | The browser application and its interactions |
| Curator or reviewer | Quality, mappings, evidence and known limitations |
| Reader or researcher | Finding and assessing relevant records |
| AI agent | Retrieving a bounded set of records while preserving evidence |

The Explorer cannot turn a poor or unofficial source into authoritative
evidence merely by displaying it well.

## A Record's Journey

Consider an imaginary catalogue entry for a dataset called “Monthly House
Prices.”

1. A public body publishes a catalogue entry.
2. A pack builder reads the entry and preserves its source URL.
3. The builder gives the record a stable route such as
   `dataset/monthly-house-prices`.
4. It normalises useful fields: title, description, publisher, dates, formats,
   licence and spatial coverage.
5. It creates relationships such as “published by” or “distributed as.”
6. It adds the record to search and facet indexes.
7. It publishes the descriptor and data files at HTTPS URLs.
8. The Explorer loads only the information needed for the first screen.
9. A reader searches for “house prices,” filters by publisher and opens the
   record.
10. The right-hand evidence card shows the normalised value, its source and any
    qualifications.

Each step can add value, but each step can also introduce error. This is why
source identity, transformation provenance, validation and visible uncertainty
matter.

## What The Explorer Is For

The product supports four connected activities:

### Find

Search for words or known entities and narrow results with filters.

### Understand

Read a record in context: its fields, related records, timeline, resources,
spatial coverage and narrative.

### Verify

Follow source links, inspect provenance and distinguish recorded facts from
normalisation or inference.

### Share Or Reproduce

Use a URL that records the active bundle, view, query, filters, sort order and
selected record where appropriate.

## What It Is Not

The Explorer is not:

- a database server that owns the source records;
- a general web crawler;
- a guarantee that every source statement is correct;
- an ontology reasoner that invents all possible consequences in the browser;
- a legal research authority or a substitute for checking enacted text;
- a map server that downloads unlimited external geometry;
- an AI answer engine that may discard citations for fluency.

These boundaries explain many implementation choices: static publication,
bounded loading, deterministic search, source-linked evidence and explicit
status labels.

## The Small And Large Paths

There are two data-loading paths.

The **small-bundle path** is easy to author and inspect. One generated JSON
file can hold every node and relationship. It is a good fit for the original
Markdown research corpus.

The **large-corpus path** starts with a descriptor and loads separate
artefacts. It is used for collections such as national data catalogues and the
complete work-level UK legislation catalogue. It avoids making every user
download every full record before seeing anything useful.

The two paths are normalised into related concepts in the interface: records,
relationships, search results, resources, publishers and views.

## The Four-Layer Discipline

Keep this distinction in mind throughout the learning path:

| Layer | Example |
|---|---|
| Source statement | The catalogue says the publisher is “Example Office” |
| Normalisation or inference | The builder maps that label to a stable publisher ID |
| Publication rule | Every dataset record must have a non-empty title |
| Presentation | The publisher appears as a blue chip in the right card |

A publication rule does not prove the source statement is true. A screen
position does not add semantic meaning. An inferred relationship should not
look like a directly observed source fact.

## Next

[Web and browser foundations](02-web-and-browser-foundations.md) explains how
the Explorer can provide this experience as a static application.