Name file (public address)

The field names of the Hahoe Genesis Protocol (HGP) are published at a public address so that other institutions’ software can read them too. This page is the human-readable description of that address.

---

1. Addresses

What	Address	Form
This description page	https://hgp.hahoe.io/ns/	page for people to read
Meaning of the field names (name file)	https://hgp.hahoe.io/ns/v1.jsonld	JSON-LD 1.1 context
Base address of the fields	https://hgp.hahoe.io/ns#	hgp:sha256 = https://hgp.hahoe.io/ns#sha256
Relation network rule table	https://hgp.hahoe.io/ns/relations-v1.json	JSON
Fixity bundle profile	https://hgp.hahoe.io/ns/#fixity-v1	section 4 of this page

• The version number is part of the address. A version, once published, is never changed. To add fields or change a meaning, a new v2 is published. Old versions stay as they are.
• The base address of the fields (ns#) stays the same across versions. The same field always has the same address.
• These open without login. Machine-readable files are served with Content-Type: application/ld+json (application/json for the rule table) and Access-Control-Allow-Origin: *, so that other institutions’ software can read them directly.

2. Fields in v1

v1 contains only the two groups in use now. The fields of the ledger (03-manifest) go into v2 once 03 is approved.

2.1 Fingerprint (02-Fingerprint)

Field	Meaning	Computation
sha256	Fingerprint of the original file	SHA-256 (FIPS 180-4), over the file bytes as they are, 64 lowercase hexadecimal characters
root	Volume fingerprint	RFC 6962 2.1 Merkle root. Leaf = SHA-256(0x00 ‖ fingerprint), internal node = SHA-256(0x01 ‖ left ‖ right), an odd node is promoted without duplication. Leaf order is the order of faces in the volume; an identical original counts only the first time (02-Fingerprint section 5)
root_version	Version of the volume fingerprint. Goes up when the faces change
method	How the volume fingerprint was made (human-readable text)
manifest	Which IIIF manifest this fixity bundle belongs to	address
canvases	One entry per canvas
canvas	IIIF canvas address	address
derivation	How the on-screen reduced copy was made from the original: crop [x0, y0, x1, y1] (original pixels), rotate (degrees), reduced_long_side (pixels)

2.2 Relation network ledger (06-Relation network)

Field	Meaning (06 section 4)
id	Identifier of the entry (UUID). When published as JSON-LD, urn:uuid: is prefixed to id, about, to and replaces
type	Kind of entry: node node, claim claim, view view
kind	Kind of node: person, group, place, event, work, thing
handle	Human-readable handle <project>:<handle>
about, to	The subject of a claim and the other party of a relation (identifiers)
prop, value	What is being stated, and its value
role	Role in an event, kinship relation (section 5)
basis	stated the source says so directly, inferred worked out by inference
source	List of source positions
when	Time of fact (edtf, original, calendar)
at	Time of record (RFC 3339)
event	What the entry does: claimed, confirmed, retracted, reopened, scope_changed
status	candidate candidate, confirmed confirmed, retracted retracted
made_by, confirmed_by	Maker (person or machine), confirmation stamp (capacity as)
scope, depositor	Scope, depositor of the source record
include, prefer, ties	Rules of a view (06 section 7)
replaces, note	The entry it replaces, a note

• The hgp field at the very start of a ledger entry (specification version, e.g. "2026.10") collides with the name of the name file, so it is not expanded as JSON-LD. When publishing as JSON-LD, put it in conformsTo.

3. How to use it in an IIIF manifest

This follows the results of testing with the official IIIF validator (hgp issue #1, arkive 2026-10-12).

• Write @context as a list, with the hgp address first and the IIIF address last: ["https://hgp.hahoe.io/ns/v1.jsonld", "http://iiif.io/api/presentation/3/context.json"]
• A canvas may carry hgp:sha256 (fingerprint of the original scan). It passes the validator.
• Do not put hgp:root on the manifest. The validator rejects it. The volume fingerprint goes in metadata (text for people) and in the fixity bundle referenced by seeAlso (for machines) (decision 0009).
• Do not put an object in place of an address in the context position. The validator rejects it.

4. Fixity bundle profile (fixity-v1)

This is the machine-readable file that the manifest’s seeAlso points to (02-Fingerprint section 9).

{"type": "Dataset", "format": "application/json",
 "profile": "https://hgp.hahoe.io/ns/#fixity-v1",
 "id": "<store>/api/books/<volume>/export/fixity"}

The fields inside the bundle are those in section 2.1. "@context": "https://hgp.hahoe.io/ns/v1.jsonld" may be placed at the top of the bundle. The earlier temporary name urn:x-hgp:fixity is replaced by this address.

• Inside the bundle, write the profile as conformsTo: "conformsTo": "https://hgp.hahoe.io/ns/#fixity-v1". profile is the name used in the manifest’s seeAlso field (IIIF) and is not in the v1 name file, so a JSON-LD processor drops a profile inside the bundle (tested 2026-10-12).

5. Relation network rule table

relations-v1.json is a table written so that machines can check “which fields go with which kind of node, what shape the values take, and whether there is one value or many”. The meaning of the fields is in 06-Relation network; this table sets only the shape.

• Two levels of violation. error is something that must not enter the ledger (no source, or a machine confirming from the start). review is something for a person to look at (two values in a field that should have one, a role name not on the list). Because 06 section 7 says superpositions are kept rather than resolved, two values is not a violation but a review.
• A claim made by a machine can never be confirmed from the start (error). Only people apply confirmation stamps (decision 0006).
• Roles in an event (role of participant) are fixed values.

Value	Korean label	Old value (still read until arkive migrates)
visitor	찾아온 이 (the one who visited)	“찾아온 이”
host	맞은 이 (the one who received the visitor)	“맞은 이”
sender	보낸 이, 준 이 (the one who sent, the one who gave)	“보낸 이”, “준 이”
recipient	받은 이 (the one who received)	“받은 이”, “받은 이(물건)” (received, of an object)
companion	함께한 이 (the one who accompanied)	“함께한 이”

Since the kind of event (event_kind) already distinguishes letters from objects, “준 이” (gave) and “보낸 이” (sent) are merged into one.

• Kinship relations (role of kin) record the form of address in the original text as is (jokjil, clan nephew; joksuk, clan uncle; oesuk, maternal uncle; and so on). Korean kinship terms are many and finely shaded in meaning, so they are not closed into a fixed list. An empty string is an error.
• The rule table is written in JSON. It could be exported to W3C SHACL (the standard for checking graphs), but that is not done for now (referenced).

6. International standards

Standard	Mapping	Grade
JSON-LD 1.1 (W3C)	v1.jsonld is a JSON-LD 1.1 context. Examples of a claim entry, a node entry, a fixity bundle and a canvas were expanded with a processor (jsonld.js 8.3.3, safe mode) and converted all the way to RDF (2026-10-12)	aligned
IIIF Presentation 3	Manifests written as in section 3 pass the official validator (6 arkive volumes)	conforms
W3C SHACL	The rule table is designed so it can be converted to SHACL	referenced