Learnlog Assistance Capture Profile and Optional Event File Representation

1.1. Scope

The proposed assistance requirements are stated in Section 2. This working revision does not yet define a complete assistance-profile conformance target; unpublished companion files do not supply normative requirements. The file, event, integrity, serialization, and registration requirements elsewhere apply when the optional Learnlog file representation is used. A carrier binding also needs to satisfy its own ecosystem's requirements. A claim about one layer does not establish conformance to the others.¶

This document defines:¶

• an experimental assistance capture profile specifying assistance states, capture requirements, explicit unavailable information, the basis of each assertion, and versioned ecosystem bindings (Section 2);¶
• proposed event families beyond assistance, for discussion and without new event types (Section 2.8);¶
• the structure of files, records, entries, and events (Section 4 through Section 6);¶
• event schemas for consent, assistance, and dialog, which are not tied to one subject area (Section 7);¶
• the canonical form, the hashes, redaction, signed heads, and verification (Section 8);¶
• two JSON serializations (Section 9);¶
• registries for file schemas and event schemas (Section 13).¶

The following are out of scope:¶

• Event schemas for subject areas. Other documents can define them.¶
• Transport and storage interfaces.¶
• Estimates of what a learner knows, such as scores or mastery values. A record states what the producer recorded. This document leaves conclusions drawn from a record to other formats.¶
• Distribution of the keys that verify signed heads.¶
• The legal basis for collecting data about learners.¶
• Decisions about whether an intervention or research finding applies in a new setting. Such decisions can cite records but are not event facts or core verification results.¶

1.2. Conventions and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Data structures are defined in the Concise Data Definition Language (CDDL) [RFC8610]. Examples are in JSON [RFC8259]. Some figures wrap long lines as described in [RFC8792].¶

This document uses the following terms:¶

Learner:

A person whose learning activity is recorded.¶

Subject:

The learner that a record is about.¶

Producer:

The software that writes a record.¶

Holder:

A party that stores a record or passes it on. The producer is the first holder.¶

Verifier:

Software that checks a record against this document.¶

Record:

A header and the entries about one subject, written by one producer. A record forms one hash chain.¶

Entry:

One element of a record. An entry carries one event and the hashes that bind it into the chain.¶

Event:

A typed description of one action.¶

Event schema:

A definition of a namespace of event types.¶

Head:

A statement that names the latest entry of a record at some moment (Section 8.4).¶

2.1. The Specific Agreement Being Proposed

The xAPI Profiles specification already provides controlled vocabularies, statement templates, and patterns [XAPI-PROFILES]. Caliper defines event and entity models with extensibility [CALIPER]. Domain work also exists: Rustici Software has proposed an AI xAPI profile [RUSTICI-AI], and GIFT documents xAPI statements for tutoring interactions, learner state, and environment adaptations [GIFT-XAPI]. Learnlog therefore makes no claim that assistance logging, domain profiling, or semantic interoperability is new, or that existing ecosystems cannot represent the necessary information.¶

The retrieved draft version 0.1.0 of the AI-Mediated Learning Interactions Profile from inXsol LLC / TLA Toolbox [TLA-AI] has direct conceptual overlap: it defines requested AI scaffolds, received AI responses, incorporated AI output, assisted and independent submission concepts, and model-version context. These are existing proposed domain definitions, not an empty vocabulary space for Learnlog to fill. Their presence does not establish that any particular submission was independent; that assertion still needs evidence about its observation boundary.¶

DataShop's Tutor Message format guide [DATASHOP-FORMAT] also defines paired help-request and tutor-response messages, with hint identifiers and ordering information. Separating a learner's request from a tutor's response therefore predates this proposal. Learnlog's candidate contribution concerns an explicit combined contract for assistance meaning, achieved capture, unavailable information, and mapping provenance; its value needs to be established against such existing work.¶

The bounded gap is that the reviewed base specifications do not by themselves require this particular combined agreement: distinct assistance lifecycle observations; a declared instrument and achieved capture boundary; explicit unavailable-information states; and provenance for mappings used in a proposed combined measurement. Profiles can supply such requirements. The proposal is to make them reusable and inspectable across products, then test their usefulness. A profile-by-profile comparison may reveal overlap, a better existing home, or requirements to remove. A separate file format is not necessary merely to express this agreement.¶

2.2. Separate the Observable Assistance States

A contract needs to define the subject of each assertion, its observation unit, the instrument that supplied it, and the evidence for that assertion. The prototype distinguishes these source-supported observations:¶

Requested:

A learner or other identified actor asked for assistance. The request does not establish that assistance was produced.¶

Offered:

The instrument observed a system or another identified actor initiate assistance, through a recorded initiation or trigger, for example step-by-step help given because of a wrong answer. An offer is established by that record, not by the absence of a request link (Section 7.2). An offer does not establish display. A declined offer is a separate observation; the absence of a recorded response does not show that an offer was ignored.¶

Generated:

A producing system generated assistance content. Internal generation does not establish transmission or display.¶

Transmitted:

The instrument observed assistance being sent to a specified destination. Sending does not establish display or use.¶

Displayed:

The instrument observed assistance being presented in a specified interface. Display does not establish attention, comprehension, or learning.¶

Accepted:

The instrument observed the interface action defined by the product as accepting assistance. Its product-specific meaning needs to remain explicit; it does not by itself establish incorporation, agreement, or learning.¶

For example, a learner requests a hint, the server generates text, and the interface displays it. There are three observed lifecycle actions. A count of requests can be one, a count of generated responses can be one, and a count of displays can be one; adding these counts does not establish three help episodes. A fourth event saying that the learner read or learned from the hint would require its own evidence. If the request and generated text are recorded but display is unobserved, observed display remains unavailable. A later analyst cannot fill that gap using the successful generation alone.¶

A count of requests leaves out assistance that a system started on its own. Two products with the same number of requests can differ in how much help learners received, so a comparison needs offered assistance to be visible as its own state. The third release in Section 2.7 gives an example of probable system-started help that a request count misses.¶

These states are proposed companion-contract concepts, not additions to the core event registry. The existing assist:help_requested and assist:scaffold_provided names and CDDL are retained. The meaning of an absent request link was revised in this revision as explicitly described in Section 7.2; unchanged syntax does not imply unchanged semantics. A new lifecycle state needs an explicit versioned event definition or binding; it cannot be inserted as an undeclared core event or equated with scaffold provision without a justified mapping.¶

2.3. Declare the Instrument and Observation Boundary

The proposed contract requires a capture instrument identifier, explicit information about which assistance states that instrument can observe, the systems and event classes inside its boundary, exclusions, an observation window, and achieved coverage. Relevant product and model identity or revision information also needs an explicit knowledge state. Capability and planned capture describe what an instrument could or intended to collect; achieved coverage describes what was captured within the stated boundary and window. One does not establish the other.¶

A claim of complete capture applies only within an explicitly stated boundary and observation window, with supporting evidence. It does not include an uninstrumented browser tab, another device, or external AI unless those are explicitly inside the demonstrated boundary. A source's completeness claim remains a source assertion. Independent checks against actual product behavior are needed to assess its accuracy. The prototype can check required fields and evidence references; it cannot establish that a producer's coverage claim is true.¶

The contract does not require raw conversations, prompts, or assistance content. A deployment should collect the minimum evidence needed for its declared purpose, use scoped identifiers, and control access and retention (Section 12). Optional source references and context can support audit without making full learner text mandatory.¶

2.4. Preserve What Is Unknown and Why

The prototype represents important assertions with an explicit knowledge state, an explanation, and evidence references. Its current states are observed, not_collected, not_reported, not_reviewed, unknown, and not_applicable. An observed value needs supporting evidence. An unavailable state must not carry a guessed observed value. These states remain candidates for review and are not asserted to be an exhaustive measurement taxonomy.¶

not_reviewed means the relevant material has not yet been examined for this assertion. not_reported requires a documented review of specified material that did not report the information. not_collected needs evidence about the capture process; silence in an export does not establish that the original system failed to collect it. unknown records an unresolved fact when a narrower supported state is unavailable. not_applicable needs a reason tied to the assertion. Review scope and evidence need to accompany these distinctions.¶

A valid record with zero displayed events therefore supports a zero only for a question whose boundary, capture evidence, inclusion rules, and denominator justify that interpretation. Otherwise, the display count may be unavailable. A missing model version remains unavailable; a transformation must not invent one from a product name or assumed release date. Data availability, a researcher's review status, and whether a study applies to a new setting are separate questions.¶

2.5. Mark Observed, Self-Reported, and Inferred Assertions

The basis of an assertion is separate from its knowledge state. This revision proposes three bases:¶

Observed:

The instrument recorded the action or presentation itself.¶

Self-reported:

The learner or another identified person stated it in answer to a named prompt or instrument. The act of reporting is observed; the content is the person's statement, not an observation of the state it describes.¶

Inferred:

A detector, model, rule, or human coder derived it from other evidence.¶

A producer implementing the proposed assistance requirements MUST record the basis of every assistance-profile assertion. An assertion without a recorded basis has an unknown basis; it is not thereby observed. An inferred assertion MUST identify the detector, model, rule, or coder; its version; the output and its scale; and the classes of input evidence it used. When the inputs are not known, they MUST carry an explicit knowledge state (Section 2.4), such as unknown or, after a documented review, not_reported, instead of being left out. An inferred assertion SHOULD also identify when the inference was made and any validation it rests on. An inferred or self-reported value MUST NOT be recorded as, or converted into, an observed value, and MUST NOT replace an observed value for the same assertion. A stated confidence and an inferred confidence for the same response are two assertions.¶

The input declaration matters when an inferred state is compared with the events it may have been computed from. If a detector's inputs include assistance events, comparing its output with assistance counts partly compares the detector with its own input. A reader can judge that only when the inputs are declared. A prediction that a learner needs help is inferred; an offer of help made because of that prediction is observed as offered (Section 2.2). An emotional state estimated from interaction logs is inferred, while a learner's answer to an emotion prompt is self-reported.¶

A classification computed from several events, such as a display followed by another request within five minutes, is an analytical result, not a new observation. It is an inferred assertion made by a rule, so the requirements above apply: it needs a versioned rule, its time window and anchor, and references to the events it used, and it MUST NOT be recorded as observed.¶

2.6. Support Existing Logging Ecosystems

The experimental bindings carry the full assistance capture payload in documented xAPI and Caliper extension locations. The xAPI materials include a draft profile with a statement template. The Caliper materials identify the applicable event model and extension requirements. The binding identifiers use example.org as unpublished draft identifiers; they are not registered or deployed vocabulary endpoints. These bindings are implementation work within established ecosystems, not a new transport protocol.¶

The draft xAPI profile identifier is https://example.org/learnlog/proposal/assistance-capture-profile, with corrected binding version 0.1.1-draft. The capture payload version remains 0.1.0-draft. It reuses the Activity Streams create verb and defines a template for creating an observation record. The current xAPI encoding targets the legacy 1.0.3 statement shape [XAPI103]; it does not claim conformance to IEEE xAPI 2.0. The Caliper 1.2 encoding uses the General Profile's base Event, a SoftwareApplication actor, Created action, and DigitalResource object, with the profile payload in event extensions. It uses the standard transport envelope without adding custom envelope properties.¶

The xAPI caller supplies an explicit account-system homepage URL and account name separately from the importer software identifier. The bounded implementation supports HTTP(S) homepages; an arbitrary importer URN is not an account homepage. Account ownership is a caller assertion, not an authenticated fact. The constructor omits Statement version. Its reader accepts stable 1.0.x Statement versions, including the 1.0.0 supplied by an LRS when absent. Statement version is distinct from the HTTP X-Experience-API-Version header. These rules follow the legacy Statement specification [XAPI103].¶

The implemented mode records an importer's creation of an observation record for a source record. Its carrier actor identifies the importer, and its carrier time identifies creation of that observation record. The source assistance assertion, its source-scoped subject identifier when available, and its native time and unavailable-information states remain inside the payload. An importing application MUST NOT invent a learner identity or substitute creation time for an unknown source action time. A server generation record does not thereby become a learner's use of a tool. Example source observations are synthetic. Live executions need the actual importer identity and creation time; fixture values do not describe an actual product or learner.¶

An importer-observation binding is useful when a retrospective source lacks the actor or time required by a native-action carrier model. It does not reconstruct a native learner event. An analyst MUST use the source assistance assertions and their evidence when counting assistance; counting carrier import events instead answers a different question. A future native-action binding needs separately justified mappings and adequate source evidence.¶

The companion software constructs complete records and performs local validation, round-trip, and rejection checks for this limited mode. Its verification reports identify the exact records, rules, and tool versions checked. Those checks do not establish certified carrier conformance, live learning-record-store exchange, preservation of original integrity guarantees, or independent cross-product interoperability. The separate evaluation toolkit's experimental encodings concern their own frozen profile and do not establish conformance to this new contract.¶

A binding to the existing Learnlog representation must use declared extension points and versioned event definitions, while preserving the current core CDDL and integrity rules. Existing records keep their original commitments. Transcoding a record does not preserve its original signature by default; a transformation needs to retain the original artifact and state any lost guarantees. Common serialization and matching names do not establish scientific equivalence. Any pooled measurement still needs an operational definition, unit, denominator, capture requirements, and a supported comparability decision.¶

2.7. Evidence From Three Released Research Datasets

This subsection is informative. The author applied the stage distinctions of Section 2.2 to three released research datasets [LEARNLOG-PREPRINT]: hint requests to an AI next-step hint tool in a programming course [HINTS-DATA], chat queries in an instrumented programming environment [IDETRACE], and problem records from a mathematics tutor [ASSISTMENTS]. The episode scripts and their aggregate outputs are public [LEARNLOG-EPISODES]. Links between stages come from the scripts' rules; the sources declare no such links. The results describe three releases, not products in general.¶

• Each release records a different subset of stages. The first records requests, system errors, and displays: of 1,050 requests, 738 were followed by a recorded display and 266 ended in an error. The second records 59 queries and their responses but no separate display; under the episode rule a response counts as a display, so its 59 requests are among the 797 below and none lacks a display. The third records hint requests and whether the learner reached the last hint, but no display events.¶
• Pooling the two programming releases gives 1,109 requests against 797 requests followed by a recorded display, a count 39% higher. The pooled share of requests without a display also hides that the second release, under that rule, has none.¶
• In the third release, the episode rule classifies 110,513 problems as steps given by the system after a wrong first answer, with no request on the main problem. A count of requests misses that help. The release records no initiation event, and only a student's first action is recorded, so under Section 2.2 these are candidates for the offered state, not established offers. The case shows why the state needs its own record.¶
• The first release contains only request episodes, so going without help cannot be counted there; the third shows that 13,607 of its 46,544 students asked for no hint on any problem or step. A pooled table could read the first release's missing count as zero, which is the error the knowledge states of Section 2.4 are meant to prevent.¶
• Every record of the third release carries four affect detector confidences, which the source describes as predicted. The pages the author could read do not say whether hint use was among the detectors' inputs. This case motivates the input declaration of Section 2.5.¶

The scripts also compute derived classes of the kind described in Section 2.5: help requested and not displayed; displayed and then requested again within five minutes (524 of 738 displays in the first release and 41 of 59 in the second); displayed with no recorded follow-up action; never requested; classified by rule as steps given by the system; and a paste with no copy inside the tool in the preceding ten minutes (291 of 1,826 pastes in the first release's activity file, which is not linked to its hint records). A paste without a prior copy can indicate outside material; it does not establish the use of external AI. Each class depends on a chosen window and anchor, which the scripts state.¶

2.8. Proposed Event Families Beyond Assistance

This subsection is informative. It proposes, for discussion, how the rules of this section could apply to other events in a learning record. It defines no event type, registers no namespace, and adds no member to the core CDDL. Each family needs a versioned event definition, a worked dataset, and review before it is specified. Only the assistance family has data behind it in this revision (Section 2.7). The inferred items below name what a separate estimate format would hold; consistent with Section 1.1, this document does not record estimates of what a learner knows. A score in the Test family is an observed scoring outcome, not such an estimate.¶

The same rules would apply to every family. An event names the stage it records; states its basis (Section 2.5); sits inside a declared capture boundary (Section 2.3); keeps unavailable information distinct from zero (Section 2.4); and identifies the assistance policy and the assistance observed before it in the same activity. A record is about one subject, so its entries are already linked. Linking events in different records to the same learner would need to be explicit and declared, use scoped identifiers, and rest on consent the deployment holds (Section 7.1, Section 12); it would never be assumed from matching identifiers. A carrier binding would need an equivalent rule for statements or events that it does not already tie to one subject. The mechanism is an open issue (Appendix F).¶

Predict:

Observed: the learner commits to a prediction before seeing an outcome. Inferred: whether the prediction reflects understanding. Linking: the prediction and the later outcome in the same episode. Appendix A.1 shows a private event of this kind. Its confidence member predates Section 2.5; under this proposal it would carry a self-reported basis and its timing.¶

Test:

Observed: an attempt and its scored result, with the scoring rule. Inferred: mastery from the result. Linking: the item and scoring-rule versions.¶

Explain:

Observed: the explanation the learner produced, or its hash. Inferred: its quality, by a named judge or model. Linking: the judge's identity or the model version.¶

Revise:

Observed: a changed answer or artifact, and what prompted the change. Inferred: whether the revision fixed the misunderstanding. Linking: the earlier and later versions of the work.¶

Defend:

Observed: a response to a challenge or counterexample. Inferred: the strength of the defense. Linking: the challenge that was posed.¶

Discern:

Observed: a choice between similar cases, such as which problem a method fits, or a judgment of whether a supplied answer, including AI output, is correct. Inferred: the concept behind the choice. Linking: the set of options shown and, where known, the correct status of each.¶

Transfer:

Observed: success on a task unlike the practiced one. Inferred: that the skill, and not something else, transferred. Linking: a declared similarity between the two tasks, which is a producer assertion.¶

Recall:

Observed: retrieval without support in the same session. Inferred: that the knowledge is available without help. Linking: whether assistance was available at the time.¶

Delayed recall:

Observed: the same retrieval after a declared delay. Inferred: that learning lasted. Linking: the same learner across records, linked with consent and declared.¶

Emotion and need:

Self-reported: a learner's own report, when one is asked for. Inferred: the state, or a predicted need for help, from a named detector. Linking: the detector, its version, its confidence, and its inputs.¶

Confidence when answering:

Self-reported: the learner's stated confidence on a declared scale, the item it refers to, and when it was given: before answering, with the answer, after answering and before feedback, or after feedback. Inferred: confidence estimated from response time, hesitation, or a model. Linking: the scored correctness of the same response and the assistance in effect before it.¶

Agency at session start and end:

Self-reported: answers to a named instrument and version, with its items and scale, at the start and at the end of a session. Observed: acts of choice during the session, such as choosing a task, setting a goal, requesting help, declining offered help, or ending the session. Inferred: agency estimated by a named model. Linking: the start and end reports of the same session and learner.¶

Delayed recall shows why linking matters. A school cannot say that a misunderstanding was fixed and stayed fixed unless the later check is linked to the same learner, the delay is declared, and the help available at both times is known. Each of those is a privacy decision as well as a measurement decision, so the proposal would make linking explicit and consent-based.¶

Confidence and agency each need two measurements. Calibration, the agreement between stated confidence and correctness, is computed from a confidence report and a scored response; it is an analytical result, not an event. Confidence given after feedback answers a different question from confidence given before it, and the two are not pooled. A change in agency between the start and end of a session is computed from two reports; an end report that is missing because the learner left early is unavailable, not unchanged.¶

Together these families would let one record show what a learner predicted, tried, explained, changed, defended, chose, carried to a new task, and remembered, with the help in effect at each point and the learner's own confidence and sense of control alongside. That is a proposal. Whether one profile should hold all of these families, or whether existing xAPI or Caliper profiles are a better home for some of them, is an open issue (Appendix F).¶

4.1. Contained Files

A LearnlogFile is one JSON text that holds one or more records. It suits export and exchange. Its file schema URI is urn:ietf:params:learnlog:file:contained.¶

The records in a file are verified one at a time. They can come from different producers and describe different subjects.¶

4.2. Sequential Files

A LearnlogFileSeq holds one record and grows by appending. It suits a log that is written while the learner works. Its file schema URI is urn:ietf:params:learnlog:file:sequential.¶

LearnlogFileSeq = {
    log-file,
    record: RecordStart
}

; every element after the first
SeqItem = Entry / SignedHead

The first element of a sequential file is the LearnlogFileSeq object. Every later element is a SeqItem. An element with a seq member is an Entry. Any other element with a head member is a SignedHead. Entries appear in order of seq. A producer writes a SignedHead after the entry that it names, and a reader accepts one at any position.¶

The Entry elements, in file order, are the entries of the record, and the SignedHead elements are its signed heads. In a sequential file, event_schemas lists the schemas known when the file is started.¶

4.3. File Schema URIs

A registered file schema uses a URN of the form urn:ietf:params:learnlog:file:<identifier> (Section 13.2). Any other file schema uses a URI that its definer controls and MUST NOT use that URN form. Such a URI is not registered.¶

5.1. Record Header

The header states what a record is about and is fixed when the record is created.¶

RecordHeader = {
    record_id: text,
    subject: text,
    hash_alg: HashAlg,
    created: Timestamp,
    ? producer: Producer,
    * text => any
}

Producer = {
    name: text,
    ? version: text,
    * text => any
}

HashAlg = "sha-256" / text

; lowercase hexadecimal
HashValue = text .regexp "([0-9a-f][0-9a-f])+"

; RFC 3339, UTC only
Timestamp = text .regexp
    "[0-9]{4}(-[0-9]{2}){2}T[0-9]{2}(:[0-9]{2}){2}([.][0-9]{1,9})?Z"

record_id:

An identifier for the record, unique among the records of the producer. A version 4 UUID [RFC9562] is RECOMMENDED.¶

subject:

A pseudonymous identifier for the learner. Section 12.1 gives the requirements.¶

hash_alg:

The hash algorithm used throughout the record. The value is a name from the IANA "Named Information Hash Algorithm Registry" [RFC6920]. That registry gives the output length of each algorithm, and the length MUST be at least 256 bits. Implementations MUST support sha-256 [FIPS180].¶

created:

The time the record was created.¶

producer:

The name and version of the software that writes the record.¶

A header MAY hold other members. The record hash (Section 8.2) covers every member, so a change to the header changes the record hash and every entry hash.¶

A Timestamp is a date and time in the format of [RFC3339], in UTC, with an uppercase T and the suffix Z. The pattern in Figure 6 admits some impossible values, such as month 13. A Timestamp MUST also be a valid date and time. The second 60 is valid only in the time 23:59:60. A HashValue is the whole output of the hash named by hash_alg, written as two lowercase hexadecimal digits for each octet.¶

5.2. Entries

Entry = {
    seq: Seq,
    time: Timestamp,
    event_hash: HashValue,
    prev_hash: HashValue,
    entry_hash: HashValue,
    ( event: Event // redacted: true )
}

; a position in a record, from 1 to (2^53)-1
Seq = 1..9007199254740991

seq:

The position of the entry in the record. The first entry of a record has seq 1. Each later entry has the seq of its predecessor plus 1. A Seq is an integer of at least 1 and below 2^53.¶

time:

The time the event occurred, as observed by the producer. Order within a record is given by seq. Values of time SHOULD NOT decrease from one entry to the next.¶

event_hash:

The hash of the event (Section 8.2).¶

prev_hash:

The hash that links the entry to what precedes it (Section 8.2).¶

entry_hash:

The hash of the entry (Section 8.2).¶

event:

The event (Section 6).¶

redacted:

Present with the value true, in place of event, when the event was removed (Section 8.3).¶

An entry holds exactly one of event and redacted.¶

A producer appends an entry when the event occurs, or as soon after as it can. A written entry keeps its position and its hashes. This document permits two changes to the entries of a record. Redaction removes an event, and a party that kept the event can put it back (Section 8.3). Truncation removes the oldest entries (Section 5.3).¶

A historical import needs to identify the action that the new event actually records. When a profile records an importer observing a source row, time is the time of that import observation, not an invented date for the original classroom action. The source timestamp, its precision, its clock basis, and any relative offset belong in the profile-defined provenance. An unavailable absolute source time remains unknown. The importer is the actor of an import-observation event; a quoted speaker is a separately identified source participant. A profile that instead represents the original action needs sufficient source evidence for the original actor and occurrence time and needs to state how that evidence was obtained. Neither construction turns a retrospective import into a contemporaneous observation by the original system.¶

5.3. Truncation

A holder can remove the oldest entries of a record, for example to meet a retention limit. The truncated member then holds the seq and entry_hash of the last entry that was removed.¶

Truncation = {
    seq: Seq,
    entry_hash: HashValue
}

The first remaining entry has a seq of truncated.seq plus 1 and a prev_hash equal to truncated.entry_hash.¶

A record can be truncated more than once. The truncated member then names the last entry removed overall. A holder can remove every entry, which leaves entries empty.¶

A signed head that names an entry before truncated.seq can no longer be compared with an entry, and a holder MAY remove it. A holder SHOULD keep every other signed head.¶

A verifier cannot check the entries that were removed. A change to the header still shows in the remaining entries, because every entry hash covers the record hash (Section 8.2). Section 11.1 states what such a check establishes.¶

6.1. Parties

A Party describes who acted or who was addressed.¶

Party = {
    role: Role,
    ? kind: "human" / "software",
    ? id: text,
    * text => any
}

Role = "learner" / "instructor" / "assistant" / "peer" /
       "guardian" / "system" / text

The role member has one of these values:¶

learner:

A person who is learning. A learner without an id is the subject of the record.¶

instructor:

A party responsible for teaching the subject in this activity.¶

assistant:

A party that responds to requests and has no teaching responsibility.¶

peer:

Another learner.¶

guardian:

A person who acts for the subject, such as a parent.¶

system:

The producer acting in none of the roles above, for example a simulation that reveals an outcome.¶

Other values MAY be used.¶

The kind member states whether the party is a person (human) or a program (software). When the member is absent, a learner, peer, or guardian is a person, and a system is a program. The member is REQUIRED with any other role. The CDDL in Figure 10 does not express this rule.¶

The id member identifies a party other than the subject. For a person, the value is pseudonymous and follows Section 12.1. For a program, the value names the program.¶

Table 1 shows how some common parties are described.¶

When the actor is a program, the instrument member (Section 6.3) describes the model or the version that produced the data.¶

6.2. Activities

The meaning of an event can depend on the task it belongs to. A producer SHOULD include activity in every event that belongs to a task.¶

Activity = {
    id: text,
    ? version: text,
    ? variant: text,
    * text => any
}

id:

An identifier for the task, such as a URI.¶

version:

The version of the task content.¶

variant:

The form of the task that this learner received, when forms differ. A random seed is one example.¶

6.3. Instruments

The instrument member states how the data of an event came to be. A reader needs it to weigh an event that a model wrote or judged.¶

Instrument = {
    source: "deterministic" / "model" / "human" / text,
    ? model: text,
    ? config_hash: HashValue,
    ? parameters: { * text => any },
    ? validated: bool,
    * text => any
}

The source member has one of these values:¶

deterministic:

Fixed program logic produced the data.¶

model:

A statistical or generative model produced the data. A hint written by a language model and a transcript of speech are examples.¶

human:

A person entered or judged the data.¶

Other values MAY be used. The remaining members are:¶

model:

The identifier and version of the model or program.¶

config_hash:

The hash of the configuration that governed the output, such as a prompt (Section 8.2). The producer chooses the octets that are hashed and needs to keep them for the hash to be of use.¶

parameters:

Settings that affect the output, such as a sampling temperature.¶

validated:

True when a deterministic check accepted the output of a model before it was used.¶

An event without an instrument member makes no statement about how its data was produced.¶

The producer.version member identifies recording software; instrument.model identifies the model or program that produced the event data. Keeping these identifiers distinct lets a reader inspect changes in either. A configuration hash identifies retained octets; it does not make those octets available, show that the named configuration was executed, or make a probabilistic output reproducible. The validated member reports a deterministic acceptance check, not empirical validation of educational effectiveness or a learner's knowledge.¶

6.4. Event Names and Event Schemas

Event types are grouped in namespaces, as in Section 8 of [QLOG]. An event schema is a document that defines a namespace or extends one. The name of an event is the namespace identifier, a colon, and the type identifier. Each identifier starts with a letter from a to z and continues with such letters, digits, or underscores.¶

Each event schema has a URI. A registered schema uses the form urn:ietf:params:learnlog:events:<namespace> (Section 13.3). A schema that extends a namespace adds a fragment identifier to the URI of that namespace. Any other schema uses a URI that its definer controls and MUST NOT use that URN form. A URI that contains a domain name SHOULD include a month and year in the form mmyyyy. Section 8.1 of [QLOG] gives the same rule, to avoid problems when a domain name changes ownership.¶

A record can hold an event whose schema a tool does not know. Such an event does not match the CDDL that the tool has. Verification (Section 8.5) checks its hashes like any others and does not depend on its schema.¶

6.5. Defining and Extending Event Types

An event schema adds each of its event types to the $Event socket. The lines below, taken from the example schema in Appendix A.1, define the event type sim:prediction_committed.¶

$Event /= event-type<"sim:prediction_committed",
                     SimPredictionCommitted>

Each data type in this document ends with a group socket named after the type, such as $$dialog-message-extension. A later schema can add members to the data type through that socket.¶

6.6. Guidance for Schema Designers

The points below apply to any event schema.¶

• Define events for actions that have meaning in the subject area, such as a prediction committed before an experiment or a claim filed with its evidence. Interface activity, such as clicks and page views, does not belong in a record unless a schema gives it that kind of meaning.¶
• Record what happened and leave conclusions out. A detected misconception is a judgment about the learner. An event that holds one SHOULD carry an instrument member.¶
• Refer to an earlier entry of the same record by its seq.¶
• Allow text written by a learner to be left out. Free text can hold personal data. A hash can stand in for the text, within the limits that Section 11.7 describes.¶
• State which members can identify a person.¶
• Prefer integers and strings to fractional numbers where exact values matter (Section 8.1).¶

6.7. Companion Profiles for AI Use

This subsection gives non-normative guidance. It adds no core fields or event types. A companion profile can use the extension points of the header and events to state context needed by a particular deployment. The profile needs its own identifier, version, and public specification. Event-schema URIs follow Section 6.4. A profile identifier is not a registration in the registries requested by this document.¶

A profile can distinguish practice, assessment, and other activity stages; identify the policy that permitted or prohibited specified assistance; and bind that policy to the relevant actor, task, stage, and period. Permission to use assistance in an activity is separate from consent to collect, use, or disclose data (Section 7.1). Neither can be inferred from the other. A policy assertion also does not establish compliance.¶

A profile can state which channels, sessions, activities, and periods the producer planned to observe, which it asserts it captured, and which it excluded. Planned capture and achieved capture are different assertions. A missing assistance event does not demonstrate that no assistance occurred. Outside applications, other devices, between-session use, a capture interruption, and unavailable content can leave relevant exposure unknown. Describing a gap does not establish that AI was used in that gap.¶

The header is fixed when a record is created (Section 5.1). A plan stated there is not a later completion report. A change in stage, applicable policy, model, configuration, or observation coverage can be represented by starting another record with the new context, or by an explicitly defined extension carried in a hashed event. A profile using such an extension needs to define its effective scope and how events refer to the context. This document defines no runtime context-update or capture-completion event, and modifying an existing header changes the hash commitments.¶

A profile can require the existing actor, activity, session, and instrument members in particular events. It can also identify where retained content or configuration is available to an authorized reviewer. A hash or content reference alone does not give that reviewer the semantic content needed to classify a scaffold, and access can be limited by Section 12. Profiles need to distinguish missing information from information that has not been reviewed.¶

Conditions such as whether AI changed practice, comparison-group exposure, or grading usually require evidence beyond one record. Condition assessments and judgments about the applicability of educational research belong in separately specified analytical records. Those records can refer to the relevant learnlog record and entries, state the reviewed scope and comparators, and preserve unresolved questions. The core verifier does not endorse those judgments or decide whether a study needs to be repeated.¶

A concrete assistance or import profile needs to publish the following as versioned, machine-readable definitions with examples and validation rules:¶

• Assistance states, such as requested, generated, delivered, or displayed, each with its source evidence and unit. These are distinct observations; a profile cannot assume that a generated response was delivered or displayed.¶
• The scope of a context assertion: actor, activity, session, stage, period, applicable assistance policy, producing instrument, planned capture, achieved capture, and gaps. Unknown, unavailable, and not yet reviewed information need distinct representations. Context changes and completion claims need effective-scope and precedence rules.¶
• Import provenance: source identifier and release, source row or event identity, original time or relative offset, importer identity and version, import time, and the relation between source speakers and event actors.¶
• Mapping definitions: the source concept and unit, target concept and unit, transformation rule, preserved distinctions, omitted or lost information, assumptions, reviewer and review status. Mapping identity and a digest show which mapping was used, not that it is substantively correct.¶
• Annotation provenance: target source spans or entry references, coding scheme and version, annotating person or instrument, review status, and the distinction between an observed action and a later classification. Overlapping annotations need explicit counting rules.¶
• For a proposed combined measurement, the operational definition, observation unit, denominator, missingness and coverage requirements, coding procedure, inclusion and exclusion rules, and review decision. Shared event names do not establish that measurements can be pooled.¶

The separate experimental companion profile qlm:assistance-context:0.1.0, version 0.1.0, is distributed with the revision -02 preparation materials. Its machine-readable definition is assistance-context-v0.1.0.json, with event schemas research-import-v2.json and assistance-lifecycle-v1.json. It defines importer observations of source-declared assistance states, per-event context with unknown defaults, and explicit mapping limits. It does not implement a capture-completion event. It is not an IETF-registered schema, is not a normative dependency of this document, and has not received independent semantic validation. Its identifier and version must accompany data that claim to use it. A deployment should publish an immutable specification and schema location before asking unrelated implementations to interoperate. A local file path or unpublished identifier does not establish public availability.¶

The informative inventory below contains 16 candidate AI-related conditions for reviewing a study and a target setting. The labels come from the project's proposed condition crosswalk version 0.1.0; they are not core event types. It is optional analytical guidance, not a validated exhaustive taxonomy, a required set of event fields, or evidence that any condition occurred. A condition needs its own supporting evidence and explicit uncertainty. Research applicability assessments and recommendations to repeat a study remain outside core verification.¶

C01:

Answer before retrieval¶

C02:

Explanation or reflection supplied¶

C03:

Feedback or scaffolding changed¶

C04:

Practice sequence or dose changed¶

C05:

Extra exposure between sessions¶

C06:

AI permitted on assessment¶

C07:

Prohibited assessment assistance¶

C08:

Comparison condition changed¶

C09:

Teacher or peer delivery changed¶

C10:

Baseline or preparation changed¶

C11:

Scoring or grading changed¶

C12:

Motivation or metacognitive signals¶

C13:

Task novelty or difficulty changed¶

C14:

Model or policy version changed¶

C15:

Access and use differ¶

C16:

Relevant exposure unobserved¶

This inventory reproduces candidate labels only. The earlier crosswalk targets an older draft, so its field selectors are not incorporated here as current requirements. Applying a condition requires a documented task, observation boundary, and supporting evidence; the label alone cannot establish occurrence, a learning effect, or a need to repeat a study.¶

7.1. The consent Namespace

The schema URI is urn:ietf:params:learnlog:events:consent. The namespace has two event types, consent:granted and consent:withdrawn. Both carry the same data.¶

ConsentChange = {
    scopes: [+ ConsentScope],
    ? ref: text,
    * $$consent-change-extension
}

ConsentScope = "instruction" / "research" / "export" / text

$Event /= event-type<"consent:granted", ConsentChange>
$Event /= event-type<"consent:withdrawn", ConsentChange>

scopes:

The uses that the consent covers.¶

ref:

A reference to the consent that the producer holds, such as the identifier of a signed form.¶

This document defines three scopes. Other values MAY be used.¶

instruction:

Use of the record to support the instruction of the subject.¶

research:

Use of the record in research.¶

export:

Disclosure of the record outside the organization that operates the producer.¶

The actor of a consent event is the party that gave or withdrew consent, for example a guardian.¶

A consent event records that consent was given or withdrawn, as the producer observed it. This document does not define how consent is obtained or how a producer acts on it.¶

A scope is in effect from a consent:granted event that names it until a later consent:withdrawn event that names it. A reader cannot tell which scopes are in effect when a consent event may be among the entries that were redacted or removed. For that reason, a holder SHOULD NOT redact a consent event.¶

7.2. The assist Namespace

The schema URI is urn:ietf:params:learnlog:events:assist. The namespace records the help that the producer observed. A reader can treat an action by the learner that follows a scaffold in the same activity as possibly assisted.¶

assist:help_requested:

The actor asked for help. The to member of the event names the party that was asked.¶

assist:scaffold_provided:

The actor gave the learner a scaffold, which is support meant to help the learner make progress. The actor can be an instructor, an assistant, a peer, or the system. The event MUST hold the actor member, because an absent actor would mean the subject.¶

The core assist:scaffold_provided event asserts that the producer observed support being given to the learner; it does not establish that the learner read, heard, used, understood, or learned from it. Content generated internally but not given to the learner is not, on that fact alone, a provided scaffold. Profiles can define separate observations for generation, transmission, delivery, and display, and state which evidence supports each. Those stages cannot be inferred from one another or counted as separate help episodes without a measurement rule. A provider's source label such as "hint" remains a source assertion unless its meaning and mapping have been reviewed.¶

The change to the interpretation of an absent request is a semantic revision, even though the CDDL and hash computations are unchanged. Consumers of historical records need to consult the source's applicable schema or profile revision and retain any explicit original assertion that a scaffold was unsolicited. They must not treat a revision -01 producer's missing link as an independently established observation of request origin, nor silently rewrite old records to add a new commitment.¶

AssistHelpRequested = {
    ? type: ScaffoldType,
    * $$assist-help-requested-extension
}

AssistScaffoldProvided = {
    type: ScaffoldType,
    ? request: Seq,
    ? level: uint .ge 1,
    ? reveals_answer: bool,
    ? modality: "text" / "speech" / text,
    ? content: text,
    ? content_ref: text,
    ? content_hash: HashValue,
    * $$assist-scaffold-provided-extension
}

ScaffoldType = "socratic" / "probing" / "metacognitive" /
               "scaffolding" / "explain" / "hint" /
               "demonstrate" / text

$Event /= event-type<"assist:help_requested", AssistHelpRequested>
$Event /= event-type<"assist:scaffold_provided",
                     AssistScaffoldProvided>

In AssistHelpRequested, type is the kind of help that was asked for, when the interface distinguishes kinds. The members of AssistScaffoldProvided are:¶

type:

The kind of scaffold (Table 2).¶

request:

The seq of the entry that this scaffold answers, such as an assist:help_requested entry or a dialog:message entry. An absent value means that this event contains no request link. It does not by itself distinguish unsolicited assistance from a request that was not observed, imported, or linked. A profile can record those cases explicitly. This clarification supersedes the inference from an absent link in revision -01.¶

level:

The delivery-order position of the scaffold among those given for the current activity, starting at 1. This is not automatically the source product's authored hint depth, pedagogical difficulty, or amount of support. A source-native hint index needs a separate profile-defined field unless a documented mapping establishes that the meanings coincide. If the delivery position is unknown, omit level.¶

reveals_answer:

True when the scaffold discloses the answer that the activity asks for.¶

modality:

How the scaffold was expressed. The default is text.¶

content:

The words of the scaffold.¶

content_ref:

An identifier for authored scaffold content.¶

content_hash:

The hash of the scaffold as shown to the learner (Section 8.2), for use when content is left out. An event MUST NOT hold both content and content_hash.¶

Other values MAY be used.¶

A producer SHOULD record every scaffold given to the learner, requested or not. The actor member identifies the provider.¶

Help can arrive as a turn in a conversation. A producer that knows a turn to be help records it as assist:scaffold_provided, with the words in content or their hash in content_hash, and writes no dialog:message for that turn. When a producer cannot tell whether a turn is help, it records the turn as dialog:message (Section 7.3). The replies of a general chat assistant are an example.¶

7.3. The dialog Namespace

The schema URI is urn:ietf:params:learnlog:events:dialog. The namespace has one event type, dialog:message, which is one turn in an exchange between the subject and another party. The actor is the party that produced the turn, and to names the party addressed.¶

DialogMessage = {
    ? modality: "text" / "speech" / text,
    ? content: text,
    ? content_hash: HashValue,
    ? reply_to: Seq,
    * $$dialog-message-extension
}

$Event /= event-type<"dialog:message", DialogMessage>

modality:

How the turn was expressed. The default is text.¶

content:

The words of the turn.¶

content_hash:

The hash of the words (Section 8.2), for use when content is left out. An event MUST NOT hold both content and content_hash.¶

reply_to:

The seq of the entry that this turn answers.¶

A producer SHOULD include activity when the exchange takes place during a task. A reader can then treat a turn by another party as possible help.¶

The words of a turn can hold personal data, and Section 12 applies. When software transcribes speech, the event SHOULD carry an instrument member that identifies the transcriber.¶

8.1. Canonical Form

Hashes are computed over a canonical form, so that two implementations produce the same octets for the same value. The canonical form of a JSON value is its serialization under the JSON Canonicalization Scheme (JCS) [RFC8785], encoded in UTF-8.¶

The following rules apply to a whole log file, including the parts that no hash covers:¶

• A log file MUST conform to I-JSON [RFC7493]. In particular, no object holds two members with the same name, and no string holds a noncharacter or a surrogate without its pair.¶
• A number is hashed as the IEEE 754 double nearest to its value, in the form that [RFC8785] gives that double. A file MUST NOT hold a number too large for a double. A number written without a fraction or an exponent MUST have an absolute value below 2^53. A larger integer is carried as a string.¶
• A string is hashed as the characters it denotes. An escape sequence and the character it stands for give the same hash. A holder MUST NOT apply Unicode normalization.¶
• A holder MUST preserve every member of a header, an event, and a head, including members it does not recognize.¶

A serialization other than JSON (Section 9.3) is mapped to the JSON data model first. Hashes are always computed over the canonical JSON form.¶

8.2. Hashes

In this section, H(x) is the hash named by hash_alg, applied to the octets x and written in lowercase hexadecimal. C(v) is the canonical form of the JSON value v.¶

record hash  = H(C(header))

event_hash   = H(C(event))

prev_hash    = record hash       in the entry with seq 1
             = entry_hash of the preceding entry, otherwise

entry_hash   = H(C({ "record_hash": record hash,
                     "seq": seq, "time": time,
                     "event_hash": event_hash,
                     "prev_hash": prev_hash }))

• The record hash is the hash of the header object.¶
• event_hash is the hash of the event object with all its members.¶
• prev_hash of the entry with seq 1 is the record hash. In every other entry, it is the entry_hash of the entry before it.¶
• entry_hash is the hash of an object with exactly five members. The member record_hash holds the record hash. The other four are the seq, time, event_hash, and prev_hash of the entry.¶
• A member named content_hash or config_hash holds the hash of a string of octets. For text, the octets are its UTF-8 encoding. For other content, the producer chooses the octets.¶

Every entry hash covers the record hash. An entry that is moved to a record with another header therefore fails step 4e of Section 8.5, even after the entries before it are removed (Section 5.3).¶

A header and an event each require members that the object hashed for an entry lacks. The canonical form of that object therefore differs from the canonical form of any header or event.¶

8.3. Redaction

A holder redacts an entry by removing its event member and adding the member redacted with the value true. No other member changes.¶

The entry hash is computed from event_hash, without the event itself. Every hash in the record therefore still verifies, and so does every signed head.¶

The salt is removed with the event. A party that does not have the salt cannot confirm a guess at the event from event_hash (Section 11.7).¶

Redaction leaves seq, time, and the hashes of the entry in place. A holder that needs to remove those as well truncates the record (Section 5.3) or deletes it.¶

A verifier reports which entries are redacted. Redaction does not cause a check to fail.¶

Only a party that kept the event can restore it. A restored event is checked against event_hash like any other.¶

8.4. Signed Heads

A head names the latest entry of a record at some moment. A producer signs a head so that a verifier can authenticate the record up to that entry.¶

SignedHead = {
    head: Head,
    signature: text
}

Head = {
    record_hash: HashValue,
    seq: Seq,
    entry_hash: HashValue,
    time: Timestamp,
    * text => any
}

record_hash:

The record hash (Section 8.2).¶

seq, entry_hash:

The seq and entry_hash of the entry that the head names.¶

time:

The time of signing, as observed by the producer.¶

The signature member is a JSON Web Signature (JWS) [RFC7515] in the compact serialization with detached content (Appendix F of [RFC7515]). The JWS payload is the canonical form of the head object. The value of signature is therefore the encoded protected header, two periods, and the encoded signature.¶

• The protected header MUST contain alg and kid and MUST NOT contain crit.¶
• The value of alg MUST name a digital signature algorithm that uses a public key. The value none and MAC algorithms such as HS256 MUST NOT be used. Implementations MUST support ES256 [RFC7518].¶
• The value of kid MUST be the JWK Thumbprint [RFC7638] of the public key, computed with SHA-256 and encoded in base64url without padding.¶

To check a signature, a verifier computes the canonical form of head, encodes it in base64url, places it between the two periods, and verifies the result as a JWS. A verifier uses each key it trusts with exactly one algorithm (Section 3.1 of [RFC8725]).¶

A producer SHOULD sign a head at the end of each session and whenever a record leaves its control.¶

This document does not define how a verifier obtains the public key or decides to trust it. A key that travels in the file itself shows nothing about who signed.¶

8.5. Verification

A verifier is configured with the public keys it trusts and, for each key, the one signature algorithm it accepts. A verifier MUST report the result that the steps below define. Any procedure that gives the same result is acceptable.¶

1. Read the file.¶

   1. Read a file that begins with the octet 0x1E as a JSON text sequence (Section 9.2). Read any other file as one JSON text (Section 9.1).¶
   2. Check that each JSON text conforms to I-JSON and to the rules for numbers in Section 8.1.¶
   3. Check that file_schema names a file schema that the verifier knows and that fits the serialization. Check that a contained file holds a records array with at least one element, and that the first element of a sequential file holds a record object.¶

   A verifier MUST reject a file when its JSON text fails this step, or when the first element of a sequential file does. None of its records is verified. A later element of a sequential file that fails step 1b is discarded (Section 9.2). Steps 2 to 5 apply to each record of a file that passes.¶

2. Check the header.¶

   1. Check that header is an object, that record_id, subject, and hash_alg are strings, and that created is a Timestamp.¶
   2. If step 2a passed and the verifier does not support hash_alg, the outcome for the record is "unsupported" and no further step applies. A verifier MUST NOT support an algorithm whose output is shorter than 256 bits.¶
   3. Compute the record hash.¶
3. Set the expected seq to 1 and the expected link to the record hash. If truncated is present, check that truncated.seq is a Seq and that truncated.entry_hash is a HashValue. The expected seq is then truncated.seq plus 1, and the expected link is truncated.entry_hash.¶

4. Check that entries is an array. For each entry, in order:¶

   1. Check that seq is a Seq, that time is a Timestamp, and that event_hash, prev_hash, and entry_hash are HashValues. Check that the entry holds exactly one of event and redacted.¶
   2. Check that seq equals the expected seq.¶
   3. Check that prev_hash equals the expected link.¶
   4. If event is present, check that it is an object, that its name has the form given in Section 6.4, that its salt matches the Salt pattern of Figure 9, and that its data is an object. Then check that the hash of the event equals event_hash. If redacted is present, check that its value is true.¶
   5. Compute the entry hash and check that it equals entry_hash.¶
   6. Set the expected link to entry_hash and add 1 to the expected seq.¶

5. If signed_heads is present, check that it is an array. For each signed head:¶

   1. Check that head is an object in which record_hash and entry_hash are HashValues, seq is a Seq, and time is a Timestamp. Check that signature consists of two base64url strings, neither of them empty, joined by two periods. Check that the first string decodes to a JSON object that conforms to I-JSON. Check that this object holds the strings alg and kid, that alg is not none, and that crit is absent.¶
   2. Check that head.record_hash equals the record hash.¶
   3. Check that head.seq is no greater than the seq of the last entry. A greater value shows that entries are missing from the end of the record. For a record without entries, the comparison uses truncated.seq, or 0 when the record is not truncated.¶
   4. If an entry has the seq that the head names, check that head.entry_hash equals its entry_hash. If head.seq equals truncated.seq, check that head.entry_hash equals truncated.entry_hash. A head with a lower seq names an entry that was removed, and this check does not apply to it.¶
   5. If the verifier trusts a key whose JWK Thumbprint equals kid, check that alg is the algorithm it accepts for that key, and verify the signature with that key as Section 8.4 describes. If the verifier trusts no such key, the signature is not checked.¶

Section 5.1 and Section 5.2 define the terms Timestamp, HashValue, and Seq. A member that this document does not define is ignored in every step, apart from its part in a hash or a signature.¶

Once a check in steps 2 to 5 fails, the outcome is settled, and a verifier MAY stop.¶

The result for a record has these parts:¶

Outcome:

"consistent" when every check in steps 2 to 5 passed, "inconsistent" when a check failed, or "unsupported" as step 2 describes.¶

Authenticated through:

For a consistent record, the highest seq among the heads that had an entry hash to compare in step 5d and a signature that verified in step 5e, together with the kid of a head that names it. This part is absent when no head qualifies. Entries up to that seq were in the record when the holder of that key signed. Later entries are consistent and unauthenticated.¶

Redacted:

The seq of each redacted entry.¶

Truncated:

The value of truncated.seq, when the record is truncated. The entries up to that seq were not checked.¶

A verifier reports the following conditions, and they leave the outcome unchanged:¶

• a time that is earlier than the one before it, with the two compared as instants;¶
• a signed head whose signature was not checked;¶
• an element of a sequential file that was discarded (Section 9.2).¶

Verification does not use title, description, serialization_format, or event_schemas. The data of an event is not checked against an event schema, and an event of an unknown type is handled like any other. A tool MAY validate events against the schemas it knows and report the result separately.¶

A consistent record agrees with itself. A verified head ties the entries up to its seq to a key. Section 11.1 states what these results establish and what they leave open.¶

9.1. JSON

A LearnlogFile is serialized as a JSON text [RFC8259] in UTF-8. The media type is application/learnlog+json, which is also the value of serialization_format. The file extension is .learnlog.¶

9.2. JSON Text Sequences

A LearnlogFileSeq is serialized as a JSON text sequence [RFC7464]. Each element is preceded by a record separator (0x1E) and followed by a line feed (0x0A). The media type is application/learnlog+json-seq, which is also the value of serialization_format. The file extension is .slearnlog.¶

A producer can add an entry or a signed head to a sequential file without rewriting what came before. Redaction and truncation rewrite the file. In Figure 18, <RS> stands for the record separator and most values are left out.¶

<RS>{"file_schema":"urn:ietf:params:learnlog:file:sequential",
     "serialization_format":"application/learnlog+json-seq",
     "record":{"header":{...},"event_schemas":[...]}}
<RS>{"seq":1,"time":"2026-10-07T14:00:05Z","event":{...},
     "event_hash":"...","prev_hash":"...","entry_hash":"..."}
<RS>{"seq":2,"time":"2026-10-07T14:01:10Z","event":{...},
     "event_hash":"...","prev_hash":"...","entry_hash":"..."}
<RS>{"head":{...},"signature":"..."}

A crash can leave the last element of a file cut off. A reader MUST discard an element that is cut off (Section 2.3 of [RFC7464]) or that fails step 1b of Section 8.5. The same applies to a parsed element that has neither the seq nor the head discriminator. An object containing seq is recognized as an Entry; otherwise an object containing head is recognized as a SignedHead (Section 4.2). A recognized object that passes step 1b but fails the structural checks in step 4 or 5 MUST make the record inconsistent; it MUST NOT be discarded as an unrecognized element. When the first element is unusable, the file is rejected. When an entry is discarded, the entries after it fail verification.¶

9.3. Other Serializations

Other serializations MAY be defined, for example one in CBOR. A serialization MUST map every structure to the JSON data model without loss, because hashes are computed over the canonical JSON form (Section 8.1).¶

11.1. What Verification Shows

A record that verifies as consistent has entries that agree with one another and with the header. Consistency alone does not show who wrote the record or that nothing was replaced. Anyone who holds a record without a signed head can change an event and recompute every later hash.¶

A signed head limits this. Take a party without the signing key that changes the seq, time, or event of an entry at or before the head. The head stays valid only when the change is a redaction, the restoring of a redacted event, or a truncation (Section 11.3). After any other such change, a verifier that trusts the key reports the record as inconsistent, or as unauthenticated when the head was removed as well.¶

Neither property shows that events took place as recorded. A producer can write an event that is false. Verification establishes at most that the signed entries were not changed by a party without the key.¶

No hash covers title, description, or event_schemas. The same holds for a member that this document does not define, unless it sits in a header, an event, or a head. A reader cannot rely on those values.¶

11.2. Removal of Recent Entries

A holder can remove the latest entries of a record together with any signed head that covers them. What remains verifies. A verifier detects the removal only if it knows a later head from another source. This document defines no way to exchange heads.¶

11.3. Redaction and Truncation by a Holder

Any holder can redact an event or truncate a record, and the result still verifies. A verifier reports which entries are redacted and whether the record is truncated. What the missing events said, and who removed them, stays unknown to the verifier.¶

A reader that draws a conclusion from the absence of an event SHOULD treat each redacted or removed entry as a possible instance of that event. A redacted entry inside an activity may have been a scaffold. A redacted or removed entry may have been a withdrawal of consent.¶

11.4. Rewriting by the Producer

The producer holds the signing key, so it can rewrite a record and sign a new head. Detection requires that another party received a head before the rewrite. A time stamping authority [RFC3161] can provide evidence that a head existed before a given time. This document does not define how to use one. The time of a head is a statement by the signer and proves nothing about when the head was signed.¶

11.5. Trusted Keys

A signature that verifies shows that the holder of a trusted key signed a head. Any trusted key authenticates any record. A verifier that trusts the keys of several producers needs to know which producer each key belongs to. The result of verification names the key for that purpose.¶

11.6. Where the Producer Runs

A signature shows that the holder of a key signed a head. When the producer runs on a device that the learner controls, the learner may control the key. A verifier needs to know where signing took place before it treats a record as evidence about that learner.¶

11.7. Guessing Redacted Events

An event can have few possible values. Without a salt, a party could hash each candidate and compare the result with event_hash. The salt prevents this only if it is unpredictable and is deleted with the event. A producer MUST NOT reuse a salt and MUST NOT derive one from the content of the event.¶

The position and time of a redacted entry stay visible, as do the entries around it. Together they can suggest what was removed.¶

Members named content_hash and config_hash carry no salt. A party can test a guess at a short or predictable text against such a hash. Redaction of the event removes these members with it.¶

11.8. Meaning of Event Names

A hash covers the name of an event. No hash covers event_schemas, the list that ties a namespace to a schema URI. For a registered namespace (Section 13.3), the name alone identifies the schema. For any other namespace, a holder can replace the URI in the list, and with it the apparent meaning of the events. A reader that depends on such events needs to know the schemas of the producer from another source.¶

For a private vocabulary or companion profile, a producer SHOULD place the schema or profile identifier, version, digest algorithm, and digest of the exact specification or schema bytes in a header extension before creating entries. The header hash already covers such an extension; no change to Section 8.2 is needed. The profile needs to define the digest scope and retrieval rules. A reader should check the protected binding rather than rely only on the unprotected event_schemas list. A digest commits to bytes, not to the correctness, availability, or equivalence of their meaning. Existing records without such bindings remain unchanged and require external knowledge; this revision does not retrofit commitments into old records.¶

11.9. Hash Algorithms

The integrity of a record rests on the collision resistance of the hash algorithm. A checksum or any other function that is not a cryptographic hash MUST NOT be used.¶

All hashes in a record use one algorithm, so a record cannot move to another. A producer that needs a new algorithm starts a new record.¶

11.10. Canonical Form

Two parsers that read the same text differently can disagree about a hash, or agree about a hash while they hold different values. Sections 4, 6, and 8.2 of [RFC8259] describe three such cases: member names that are not unique, numbers beyond the range or precision of a double, and strings with unpaired surrogates. The rules in Section 8.1 address these cases, and step 1 of Section 8.5 applies them before any hash is computed.¶

11.11. Untrusted Input

A log file can come from a source that is not trusted. Implementations need limits on file size, nesting depth, and string length.¶

12.1. Identifiers

The subject member, and the id member of a party that is a person, MUST NOT hold a name, an email address, or an identifier taken from another system, such as a student number.¶

A RECOMMENDED construction is HMAC [RFC2104] with SHA-256 over the internal identifier, under a secret key that the producer keeps, with at least 128 bits of the output retained. A hash without a key is not sufficient, because identifiers can be guessed and hashed.¶

The subject identifier is part of the header and stays fixed for the life of a record. Every party that receives the record sees the same identifier and can link the record to other copies.¶

12.2. People Other Than the Subject

A record can describe instructors, peers, and guardians, and a dialog event can hold their words. The data is then about them as well. Their identifiers follow Section 12.1.¶

12.3. Data Minimization

• A producer SHOULD record an event only if the event has a use.¶
• A producer SHOULD use no more precision in time than its purpose needs. Precision cannot be reduced later, because time is hashed.¶
• Text written by a learner SHOULD be left out unless it is needed.¶

12.4. Limits of Redaction

Redaction removes the content of an event. The entry retains a commitment and a producer-reported time. It does not establish that an action occurred or that the time is accurate. Copies of the content in other events, or outside the record, are not affected.¶

The event_hash of a redacted entry remains as well. A party that kept a copy of the event can still show that the event belonged to the record. Truncation or deletion of the record removes that hash.¶

Redaction may not be enough after consent is withdrawn. Truncation or deletion of the record removes more. Unless it is redacted or removed, the consent:withdrawn event remains in the record as the trace of the withdrawal.¶

12.5. Correlation and Identification

The actions and times in a record can be combined with other data about a person. Sections 5.2.1 and 5.2.2 of [RFC6973] describe how such correlation can lead to identification. A record SHOULD be treated as personal data whatever identifiers it carries.¶

12.6. Signing Keys

The kid of a signed head is the same in every record signed with one key. A key used only for one learner can link that learner's records despite different subject identifiers. A device-specific key groups that device's records and may cover several learners. A deployment-wide key groups the deployment's records but does not by itself distinguish one learner from another. Other metadata can still support linkage.¶

12.7. Storage and Transfer

Records SHOULD be encrypted in transit and at rest. Access to them SHOULD be controlled and logged. A holder SHOULD set a retention period.¶

12.8. Children

A learner can be a child. This document does not address compliance with any law.¶

Inferred emotional states, stated confidence, and agency reports (Section 2.8) can be sensitive, especially for children. A deployment that collects them needs a declared purpose. An inferred state about one learner carries the uncertainty of its detector and does not establish that learner's state.¶

13.1. URN Sub-namespace

IANA is requested to register the following in the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry [RFC3553]:¶

Registry name:

learnlog¶

Specification:

This document¶

Repository:

https://www.iana.org/assignments/learnlog¶

Index value:

The part of a URN that follows urn:ietf:params:learnlog:, which has the form file:<identifier> or events:<namespace>. No transformation is needed.¶

13.2. File Schema URIs

IANA is requested to create the "learnlog File Schema URIs" registry at https://www.iana.org/assignments/learnlog. The registration policy is Expert Review [RFC8126]. The expert checks that the URI has the form given in Section 4.3 and that a public specification defines the file schema. An entry holds a file schema URI, a description, and a reference. The initial entries are:¶

File Schema URI:

urn:ietf:params:learnlog:file:contained¶

Description:

A file that holds one or more records¶

Reference:

Section 4.1¶

File Schema URI:

urn:ietf:params:learnlog:file:sequential¶

Description:

A file that holds one record and grows by appending¶

Reference:

Section 4.2¶

13.3. Event Schema URIs

IANA is requested to create the "learnlog Event Schema URIs" registry at the same location. The registration policy is Expert Review [RFC8126]. The expert checks the following:¶

• The URI has the form given in Section 6.4.¶
• A public specification defines the event types, with CDDL for the data of each.¶
• A schema for a new namespace uses a namespace identifier that is not yet registered.¶
• A schema that extends a registered namespace uses the URI of that namespace with a fragment identifier, and leaves the registered event types unchanged.¶

An entry holds an event schema URI, a namespace, the event types, a description, and a reference. The initial entries are:¶

Event Schema URI:

urn:ietf:params:learnlog:events:consent¶

Namespace:

consent¶

Event Types:

granted, withdrawn¶

Description:

Consent given or withdrawn¶

Reference:

Section 7.1¶

Event Schema URI:

urn:ietf:params:learnlog:events:assist¶

Namespace:

assist¶

Event Types:

help_requested, scaffold_provided¶

Description:

Help requested and scaffolds provided¶

Reference:

Section 7.2¶

Event Schema URI:

urn:ietf:params:learnlog:events:dialog¶

Namespace:

dialog¶

Event Types:

message¶

Description:

Turns in an exchange with another party¶

Reference:

Section 7.3¶

13.4. Media Types

IANA is requested to register the following media types [RFC6838].¶

A.1. An Example Event Schema

The example uses a private event schema with the namespace sim and the URI https://example.org/102026/sim. It defines two event types for a simulation.¶

SimPredictionCommitted = {
    prediction: text,
    ? confidence: "guess" / "fairly_sure" / "certain",
    * $$sim-prediction-committed-extension
}

SimExplanationFiled = {
    explanation: text,
    * $$sim-explanation-filed-extension
}

$Event /= event-type<"sim:prediction_committed",
                     SimPredictionCommitted>
$Event /= event-type<"sim:explanation_filed", SimExplanationFiled>

A.2. A Complete File

The file in Figure 20 holds one record with eight entries and one signed head. Entry 4 is a hint from a tutoring system. Entries 5 and 6 are an exchange with an AI chat assistant. Entry 7 is a spoken hint from a teacher, transcribed by software.¶

The content_hash and config_hash values are hashes of the texts in Table 3. Each text is one line, with single spaces between words and no line ending.¶

The explanation in entry 8 holds the character U+00BE, written in the figure as an escape. In the canonical form, that character is the two octets C2 BE.¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{
  "file_schema": "urn:ietf:params:learnlog:file:contained",
  "serialization_format": "application/learnlog+json",
  "title": "Example record",
  "records": [
    {
      "header": {
        "record_id": "66a921d7-55be-4589-afcc-84ea4d2c26ef",
        "subject": "L-fdda6e0e3413590a303a3737d4176389",
        "hash_alg": "sha-256",
        "created": "2026-10-07T14:00:00Z",
        "producer": {"name": "example-sim", "version": "1.4.0"}
      },
      "event_schemas": [
        "urn:ietf:params:learnlog:events:consent",
        "urn:ietf:params:learnlog:events:assist",
        "urn:ietf:params:learnlog:events:dialog",
        "https://example.org/102026/sim"
      ],
      "entries": [
        {
          "seq": 1,
          "time": "2026-10-07T14:00:05Z",
          "event": {
            "name": "consent:granted",
            "salt": "SUe3daeuE7ZsSfKRHA9RkQ",
            "actor": {"role": "guardian", "kind": "human"},
            "data": {"scopes": ["instruction", "research"]}
          },
          "event_hash": "0e144a6edfb39ded22fab2dba4f60a69dc9fc72cdfe\
7006ab78001e5ac11deef",
          "prev_hash": "dcfc869849b6088bb8cba0761987f4fa90a181335e20\
a95b120bb0e8dfcd5556",
          "entry_hash": "ff3f6b48ed7a77379e68a08f6a0c2bfa71bdc757671\
ceb88d905e5d307638433"
        },
        {
          "seq": 2,
          "time": "2026-10-07T14:01:10Z",
          "event": {
            "name": "sim:prediction_committed",
            "salt": "yqUo0sZAN2gYAhADsPJjKw",
            "session": "s-01",
            "activity": {
              "id": "https://example.org/activities/ratio-mixing",
              "version": "2.0",
              "variant": "seed-8675309"
            },
            "data": {
              "prediction": "3:4",
              "confidence": "fairly_sure"
            }
          },
          "event_hash": "1b878146c3e51d20d0411979dc7fbac81da5fd08846\
9a725b9afcf8395c2a518",
          "prev_hash": "ff3f6b48ed7a77379e68a08f6a0c2bfa71bdc757671c\
eb88d905e5d307638433",
          "entry_hash": "ac64c6867336279286d1837e60312b56b106978d648\
db62360f211306d65b6e5"
        },
        {
          "seq": 3,
          "time": "2026-10-07T14:01:42Z",
          "event": {
            "name": "assist:help_requested",
            "salt": "eKmBaP2uRROEiC4HVbWZfA",
            "to": {
              "role": "instructor",
              "kind": "software",
              "id": "example-tutor"
            },
            "session": "s-01",
            "activity": {
              "id": "https://example.org/activities/ratio-mixing",
              "version": "2.0",
              "variant": "seed-8675309"
            },
            "data": {"type": "hint"}
          },
          "event_hash": "5485100233e98c7bca12183cf9f9da23ee91f8bb029\
d82e46ddab320661cc51b",
          "prev_hash": "ac64c6867336279286d1837e60312b56b106978d648d\
b62360f211306d65b6e5",
          "entry_hash": "afa914e1952ca0d6878b901e32279a09f1462f252df\
b3f289ea846c63b048e06"
        },
        {
          "seq": 4,
          "time": "2026-10-07T14:01:43.200Z",
          "event": {
            "name": "assist:scaffold_provided",
            "salt": "DgQiQwSuZLoHwnBLIox60g",
            "actor": {
              "role": "instructor",
              "kind": "software",
              "id": "example-tutor"
            },
            "session": "s-01",
            "activity": {
              "id": "https://example.org/activities/ratio-mixing",
              "version": "2.0",
              "variant": "seed-8675309"
            },
            "instrument": {
              "source": "model",
              "model": "example-tutor-2026-09",
              "config_hash": "c9f3b7ca43165de9e1df7bc7ec6cff14e7498d\
a4250a6df8e8f1885a9b4aeea8",
              "parameters": {"temperature": 0.2}
            },
            "data": {
              "type": "hint",
              "request": 3,
              "level": 1,
              "reveals_answer": false,
              "content_hash": "86c2216ed616d2d0097475056db432d1f9f76\
e1ac5e712742157a3fe64ded70d"
            }
          },
          "event_hash": "b4bd1e82ee9019fb8ece8ab96192a64fdc953fc9ab2\
7b2d046664ac8525cc789",
          "prev_hash": "afa914e1952ca0d6878b901e32279a09f1462f252dfb\
3f289ea846c63b048e06",
          "entry_hash": "3b8fb5a69bc9701329888b081538f1cc243a2fadb14\
8f6fc2f619de4f7671f61"
        },
        {
          "seq": 5,
          "time": "2026-10-07T14:02:30Z",
          "event": {
            "name": "dialog:message",
            "salt": "HySIGmOXiD_e0G3jppGMVg",
            "to": {
              "role": "assistant",
              "kind": "software",
              "id": "example-chat"
            },
            "session": "s-01",
            "activity": {
              "id": "https://example.org/activities/ratio-mixing",
              "version": "2.0",
              "variant": "seed-8675309"
            },
            "data": {
              "modality": "text",
              "content": "What does simplifying a ratio mean?"
            }
          },
          "event_hash": "a83a6d085d8ae61dfe3b3783ecaea3c51d52588d7a4\
c2182245236b2b0b7d2dd",
          "prev_hash": "3b8fb5a69bc9701329888b081538f1cc243a2fadb148\
f6fc2f619de4f7671f61",
          "entry_hash": "4cf6025ac1e0aa85ed8a9f1e3c678f544a73319d1e0\
8eecb3fbe6ae695b65a2d"
        },
        {
          "seq": 6,
          "time": "2026-10-07T14:02:33.500Z",
          "event": {
            "name": "dialog:message",
            "salt": "wf_VFXE_2WNouptIJguFuQ",
            "actor": {
              "role": "assistant",
              "kind": "software",
              "id": "example-chat"
            },
            "session": "s-01",
            "activity": {
              "id": "https://example.org/activities/ratio-mixing",
              "version": "2.0",
              "variant": "seed-8675309"
            },
            "instrument": {
              "source": "model",
              "model": "example-chat-2026-08",
              "config_hash": "fcfd5153bc5c0d1f52417f66ab078c749eb21f\
4cebb5504cf274821a79a17aa5"
            },
            "data": {
              "modality": "text",
              "reply_to": 5,
              "content_hash": "fb4ede48d160a985aeca77af68fcc7abdc3af\
cdbff6781574146ecd02c2b45ed"
            }
          },
          "event_hash": "0d8d14d15cb3a606a857e86fc4fbe838a9ec11dfa3e\
bdb73a5eef53bbb96d4c9",
          "prev_hash": "4cf6025ac1e0aa85ed8a9f1e3c678f544a73319d1e08\
eecb3fbe6ae695b65a2d",
          "entry_hash": "43f068599a10f02217bc7287ca082d99818aa1fd92f\
a3e12115cf1a7d5bfc23b"
        },
        {
          "seq": 7,
          "time": "2026-10-07T14:03:05Z",
          "event": {
            "name": "assist:scaffold_provided",
            "salt": "lMgpY68f-AMZ-mEMbfR3cg",
            "actor": {
              "role": "instructor",
              "kind": "human",
              "id": "T-c1a8a3a416c9098d21b2baf451464304"
            },
            "session": "s-01",
            "activity": {
              "id": "https://example.org/activities/ratio-mixing",
              "version": "2.0",
              "variant": "seed-8675309"
            },
            "instrument": {
              "source": "model",
              "model": "example-transcriber-1"
            },
            "data": {
              "type": "hint",
              "level": 2,
              "reveals_answer": false,
              "modality": "speech",
              "content": "Try it with the smaller numbers first."
            }
          },
          "event_hash": "3e305baf5a3fad47f1e9c3d412d799fdd18926ff159\
169a26034af74e6214f91",
          "prev_hash": "43f068599a10f02217bc7287ca082d99818aa1fd92fa\
3e12115cf1a7d5bfc23b",
          "entry_hash": "4a0646f97bb877a347b7ba98eb6d1a7d9e0e3e0978e\
d5706b0e07b7ef6ec4668"
        },
        {
          "seq": 8,
          "time": "2026-10-07T14:04:20Z",
          "event": {
            "name": "sim:explanation_filed",
            "salt": "y0_vEXCW8JNMCBA0MnLr2w",
            "session": "s-01",
            "activity": {
              "id": "https://example.org/activities/ratio-mixing",
              "version": "2.0",
              "variant": "seed-8675309"
            },
            "data": {
              "explanation": "12 out of 16 is \u00be. Both divide b\
y 4."
            }
          },
          "event_hash": "3689aa3e1f8fdea9494f10a9607ffd84db805ad0475\
f57077129a34cd8ebb5d0",
          "prev_hash": "4a0646f97bb877a347b7ba98eb6d1a7d9e0e3e0978ed\
5706b0e07b7ef6ec4668",
          "entry_hash": "d2b47063f53bcce905ef687c5f7f1c3f008078d0a3e\
ece78d2bc54bf8c1ca5b5"
        }
      ],
      "signed_heads": [
        {
          "head": {
            "record_hash": "dcfc869849b6088bb8cba0761987f4fa90a18133\
5e20a95b120bb0e8dfcd5556",
            "seq": 8,
            "entry_hash": "d2b47063f53bcce905ef687c5f7f1c3f008078d0a\
3eece78d2bc54bf8c1ca5b5",
            "time": "2026-10-07T14:04:21Z"
          },
          "signature": "eyJhbGciOiJFUzI1NiIsImtpZCI6IkNPSWFUYTctOFoz\
VElOYmhBOFJjczZmcjAyWlRERzExMzM3MVQzR01aUlUifQ..9SbLqNvt-_gfXkz4sYqC\
znBecvxy1YojXXOujGN2pdy5jJ7IZOOw37pxBsrdjr7K4p52Rqlo4va5MGFbP5vVWg"
        }
      ]
    }
  ]
}

A.3. Intermediate Values

The canonical form of the header is:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{"created":"2026-10-07T14:00:00Z","hash_alg":"sha-256","producer":{"\
name":"example-sim","version":"1.4.0"},"record_id":"66a921d7-55be-45\
89-afcc-84ea4d2c26ef","subject":"L-fdda6e0e3413590a303a3737d4176389"}

Its SHA-256 hash is the record hash, which is also the prev_hash of entry 1:¶

dcfc869849b6088bb8cba0761987f4fa90a181335e20a95b120bb0e8dfcd5556

The canonical form of the event in entry 2 is:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{"activity":{"id":"https://example.org/activities/ratio-mixing","var\
iant":"seed-8675309","version":"2.0"},"data":{"confidence":"fairly_s\
ure","prediction":"3:4"},"name":"sim:prediction_committed","salt":"y\
qUo0sZAN2gYAhADsPJjKw","session":"s-01"}

Its hash is the event_hash of entry 2:¶

1b878146c3e51d20d0411979dc7fbac81da5fd088469a725b9afcf8395c2a518

The canonical form of the object that is hashed for entry 2 is:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{"event_hash":"1b878146c3e51d20d0411979dc7fbac81da5fd088469a725b9afc\
f8395c2a518","prev_hash":"ff3f6b48ed7a77379e68a08f6a0c2bfa71bdc75767\
1ceb88d905e5d307638433","record_hash":"dcfc869849b6088bb8cba0761987f\
4fa90a181335e20a95b120bb0e8dfcd5556","seq":2,"time":"2026-10-07T14:0\
1:10Z"}

Its hash is the entry_hash of entry 2:¶

ac64c6867336279286d1837e60312b56b106978d648db62360f211306d65b6e5

A.4. The Signed Head

The head was signed with the private key that matches this public key:¶

{
  "kty": "EC",
  "crv": "P-256",
  "x": "hLOF5epJKOENr_YLdw3iuvlSeuuUdVewL1BqcNtOKYw",
  "y": "PwQdWqmdT3_EOKIQvttI8kFeZLUePMifTFD5CpM-1WY"
}

The JWK Thumbprint of the key, used as kid, is:¶

COIaTa7-8Z3TINbhA8Rcs6fr02ZTDG113371T3GMZRU

The protected header is:¶

{"alg":"ES256","kid":"COIaTa7-8Z3TINbhA8Rcs6fr02ZTDG113371T3GMZRU"}

The JWS payload is the canonical form of the head:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{"entry_hash":"d2b47063f53bcce905ef687c5f7f1c3f008078d0a3eece78d2bc5\
4bf8c1ca5b5","record_hash":"dcfc869849b6088bb8cba0761987f4fa90a18133\
5e20a95b120bb0e8dfcd5556","seq":8,"time":"2026-10-07T14:04:21Z"}

The value of signature in the file is:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

eyJhbGciOiJFUzI1NiIsImtpZCI6IkNPSWFUYTctOFozVElOYmhBOFJjczZmcjAyWlRE\
RzExMzM3MVQzR01aUlUifQ..9SbLqNvt-_gfXkz4sYqCznBecvxy1YojXXOujGN2pdy5\
jJ7IZOOw37pxBsrdjr7K4p52Rqlo4va5MGFbP5vVWg

The private key is not given here, so an implementation cannot reproduce this value. The value can be verified with the public key above.¶

A.5. Redaction and Truncation

After entry 8 is redacted, it reads as shown below. Every hash in the record and the signed head verify as before.¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{
  "seq": 8,
  "time": "2026-10-07T14:04:20Z",
  "redacted": true,
  "event_hash": "3689aa3e1f8fdea9494f10a9607ffd84db805ad0475f5707712\
9a34cd8ebb5d0",
  "prev_hash": "4a0646f97bb877a347b7ba98eb6d1a7d9e0e3e0978ed5706b0e0\
7b7ef6ec4668",
  "entry_hash": "d2b47063f53bcce905ef687c5f7f1c3f008078d0a3eece78d2b\
c54bf8c1ca5b5"
}

If entries 1 to 5 are removed from the original record instead, the record gains the member shown below and its first remaining entry is entry 6. The signed head still verifies.¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{
  "truncated": {
    "seq": 5,
    "entry_hash": "4cf6025ac1e0aa85ed8a9f1e3c678f544a73319d1e08eecb3\
fbe6ae695b65a2d"
  }
}

A.6. Canonical Form Check

The record above has few values that separate the canonical form of [RFC8785] from other compact JSON output with sorted member names. The JSON text in Figure 21 has more of them. It holds numbers in several spellings, a control character, and two member names whose order by UTF-16 code unit differs from their order by code point.¶

{
  "numbers": [1e21, 1.0, 0.000001, 1e-7, -0, 0.2, 4.50, 2E-3,
              333333333.33333329],
  "string": "\u000f\u00be/\"\\\n",
  "\ud83d\ude00": 1,
  "\ufb33": 2,
  "a": null,
  "A": true
}

In the canonical form, the member names appear in the order A, a, numbers, string, U+1F600, U+FB33. The numbers appear as 1e+21, 1, 0.000001, 1e-7, 0, 0.2, 4.5, 0.002, and 333333333.3333333. The canonical form has 131 octets, shown here in hexadecimal:¶

7b 22 41 22 3a 74 72 75 65 2c 22 61 22 3a 6e 75
6c 6c 2c 22 6e 75 6d 62 65 72 73 22 3a 5b 31 65
2b 32 31 2c 31 2c 30 2e 30 30 30 30 30 31 2c 31
65 2d 37 2c 30 2c 30 2e 32 2c 34 2e 35 2c 30 2e
30 30 32 2c 33 33 33 33 33 33 33 33 33 2e 33 33
33 33 33 33 33 5d 2c 22 73 74 72 69 6e 67 22 3a
22 5c 75 30 30 30 66 c2 be 2f 5c 22 5c 5c 5c 6e
22 2c 22 f0 9f 98 80 22 3a 31 2c 22 ef ac b3 22
3a 32 7d

The SHA-256 hash of those octets is:¶

afbc268398163c4f856a4d881d1eb85ba85b85e609c8473a11ebaf56cf28a0d1