Quantum Learning Machines

kumar@quantumlearningmachines.com

education learning logging integrity redaction This document defines learnlog, a log format for learning software. A record holds typed events that describe what a learner did and what other parties, human or software, did in response. Entries are chained by hash, and a producer can sign the chain. A reader who trusts the signing key can then detect changes to the entries under a signed head that were made without that key. Some changes remain undetectable, and the security considerations list them. An event can be redacted, and the rest of the record still verifies. The format defines files, records, entries, events, and registries for event schemas. Event schemas for specific subject areas are out of scope. Note to Readers This first draft is a proposal for discussion. lists open questions. describes an earlier implementation.

Introduction This document defines learnlog, a log format for learning software. The format has two aims. The first is to record actions that have meaning in the subject being learned, as distinct from interface activity such as clicks and page views. The second is to let a reader check a record for changes, within the limits that states. Both aims cover the help that a learner receives, whether from a teacher, a tutoring system, or an AI assistant. The format has the following properties:

• Events are typed. An event schema defines the event types of one area, such as a prediction committed in a simulation ().
• Every event can state who acted and toward whom. A request for help and a scaffold given in reply are events of their own, whether the helper is a person or a program (, ).
• Entries are chained by hash, and a producer can sign the latest hash. A reader who trusts the signing key can then detect a change to the signed entries that was made without that key (). states the limits.
• An event can be redacted without breaking the chain ().
• Records are kept in files. A record can be written, and its hashes checked, without a server.

The structure of files, records, and event schemas follows qlog , which defines structured logging for network protocols. This document adds integrity rules and the members that a record of learning needs.

Scope This document defines:

• the structure of files, records, entries, and events ( through );
• event schemas for consent, assistance, and dialog, which are not tied to one subject area ();
• the canonical form, the hashes, redaction, signed heads, and verification ();
• two JSON serializations ();
• registries for file schemas and event schemas ().

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.

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 when, and only when, they appear in all capitals, as shown here. Data structures are defined in the Concise Data Definition Language (CDDL) . Examples are in JSON . Some figures wrap long lines as described in . 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 ().

Design Overview A log file holds one or more records. A record holds a header and a sequence of entries. Each entry holds one event.

Structure of a log file

Each entry holds the hash of its event and the hash of the entry before it. The first entry holds the hash of the header, and every entry hash covers that hash as well. A change to the header or to an earlier entry therefore changes every later entry hash. A producer can sign a statement of the latest entry hash, which gives a verifier a fixed point to check against.

The hash chain of a record

An entry commits to the hash of its event. The event itself can be removed later, and the chain still verifies (). Event types live in namespaces that event schemas define. This document defines schemas for three namespaces that are not tied to one subject area. Other schemas are identified by URI.

Log Files A log file takes one of two forms. A contained file holds one or more records (). A sequential file holds one record and grows by appending (). Both forms hold the members of the log-file group, as in .

LearnlogFile and the members common to all log files

file_schema:

A URI that identifies the file schema ().

serialization_format:

The media type of the serialization ().

title, description:

Free text about the file. These members SHOULD NOT hold information about a learner.

No hash covers these members. A producer SHOULD write file_schema and serialization_format within the first 256 octets of a file, as also asks, so that a tool can identify the file from its start. The CDDL in this document has two root rules, LearnlogFile and LearnlogFileSeq. A third rule, SeqItem, describes each later element of a sequential file.

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.

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 definition

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.

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

Records A record holds a header and the entries about one subject, written by one producer.

Record definition

header:

The record header ().

event_schemas:

The URIs of the event schemas used in the record (). As in , the list is a hint to tools about the event namespaces in the record. No hash covers it (), and it can grow with the record. A record MAY hold events from schemas that are not listed.

truncated:

Present when the oldest entries were removed ().

entries:

The entries, in order of seq ().

signed_heads:

Signatures by the producer over heads of this record ().

The CDDL in this document defines what a producer writes. A reader MUST ignore a member that it does not recognize, wherever the member appears. A hash or a signature covers such a member only in a header, an event, or a head. A producer SHOULD NOT add members anywhere else.

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

RecordHeader definition 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 is RECOMMENDED.

subject:

A pseudonymous identifier for the learner. 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" . That registry gives the output length of each algorithm, and the length MUST be at least 256 bits. Implementations MUST support sha-256 .

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 () 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 , in UTC, with an uppercase T and the suffix Z. The pattern in 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.

Entries

Entry definition

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 ().

prev_hash:

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

entry_hash:

The hash of the entry ().

event:

The event ().

redacted:

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

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 (). Truncation removes the oldest entries ().

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 definition

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 (). states what such a check establishes.

Events An event describes one action: something the learner did, or something another party did that bears on the learner's work.

Event definition = { name: Name, salt: Salt, data: Data, ? actor: Party, ? to: Party, ? session: text, ? activity: Activity, ? instrument: Instrument, * text => any } ; 22 or more characters of the base64url alphabet Salt = text .regexp "[A-Za-z0-9_-]{22,}" ]]>

The event-type rule is a CDDL generic. An event type is an instance of the rule that fixes the name and the type of data. The $Event socket collects the instances ().

name:

The event type, written as a namespace, a colon, and a type identifier ().

salt:

A random value that keeps a removed event from being guessed from its hash (). For each event, a producer MUST generate at least 16 octets from a cryptographically secure source and encode them in base64url without padding .

data:

An object with the members that the event type defines.

actor:

The party that performed the action (). When absent, the actor is the subject.

to:

The party the action was directed at (). When absent, an action by another party was directed at the subject. An action by the subject then has no stated addressee.

session:

An identifier that groups the events of one continuous period of use.

activity:

The task in which the action took place ().

instrument:

How the data of the event was produced ().

An event MAY hold other members. The event hash covers every member of the event.

Parties A Party describes who acted or who was addressed.

Party definition 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 does not express this rule. The id member identifies a party other than the subject. For a person, the value is pseudonymous and follows . For a program, the value names the program. shows how some common parties are described. Examples of parties

Party	role	kind
A teacher working with the learner	instructor	human
An intelligent tutoring system	instructor	software
A general AI chat assistant	assistant	software
A classmate	peer	human

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

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 definition 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.

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 definition 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 (). 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.

Event Names and Event Schemas Event types are grouped in namespaces, as in . 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> (). 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. 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 () checks its hashes like any others and does not depend on its schema.

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 , define the event type sim:prediction_committed. ]]> 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.

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 describes.
• State which members can identify a person.
• Prefer integers and strings to fractional numbers where exact values matter ().

Generic Event Schemas This section defines event schemas for three namespaces that are not tied to one subject area: consent, assist, and dialog.

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.

Events of the consent namespace $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.

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.

Events of the assist namespace $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 ().

request:

The seq of the entry that this scaffold answers, such as an assist:help_requested entry or a dialog:message entry. Absent when the scaffold was not requested.

level:

The position of the scaffold among those given for the current activity, starting at 1.

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 (), for use when content is left out. An event MUST NOT hold both content and content_hash.

Values of ScaffoldType

Value	Meaning
socratic	An open question that leads the learner toward an idea
probing	A question about an assumption the learner made
metacognitive	A prompt about the learner's own approach
scaffolding	The problem broken into parts
explain	A direct explanation
hint	A hint
demonstrate	A worked example

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 (). The replies of a general chat assistant are an example.

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.

Events of the dialog namespace ]]>

modality:

How the turn was expressed. The default is text.

content:

The words of the turn.

content_hash:

The hash of the words (), 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 applies. When software transcribes speech, the event SHOULD carry an instrument member that identifies the transcriber.

Integrity

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) , 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 . 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 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 () is mapped to the JSON data model first. Hashes are always computed over the canonical JSON form.

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.

Hash computation

• 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 , even after the entries before it are removed (). 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.

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 (). Redaction leaves seq, time, and the hashes of the entry in place. A holder that needs to remove those as well truncates the record () 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.

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 definition any } ]]>

record_hash:

The record hash ().

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) in the compact serialization with detached content (). 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 .
• The value of kid MUST be the JWK Thumbprint 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 (). 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.

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 (). Read any other file as one JSON text ().
   2. Check that each JSON text conforms to I-JSON and to the rules for numbers in .
   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 (). 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 , that its salt matches the Salt pattern of , 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 describes. If the verifier trusts no such key, the signature is not checked.

and 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 ().

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. states what these results establish and what they leave open.

Serialization The structures in this document are defined in CDDL. takes the same approach and maps its structures to JSON and to JSON text sequences. This document defines the same two serializations. Hashes always use the canonical JSON form (). Where this document defines a member as an integer, a producer writes the number without a fraction or an exponent. A reader compares numbers by value.

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

JSON Text Sequences A LearnlogFileSeq is serialized as a JSON text sequence . 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 , <RS> stands for the record separator and most values are left out.

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

A crash can leave the last element of a file cut off. A reader MUST discard an element that is cut off () or that fails step 1b of . The same applies to an element that is neither an Entry nor a SignedHead. When the first element is unusable, the file is rejected. When an entry is discarded, the entries after it fail verification.

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 ().

Relationship to Existing Work The file structure and the event schema model come from qlog . A learnlog record corresponds to a qlog trace (). This document adds hashes, redaction, and signed heads. The Experience API (xAPI) defines a JSON data model and a web service for communication between activities and a Learning Record Store. This document defines a file format and no web service. A mapping between the two is not defined here. Caliper Analytics defines events and entities, and an envelope that carries them to an endpoint. This document defines no transport. Redaction relies on salted hashes, an approach that Selective Disclosure for JSON Web Tokens also uses (). A signed head is similar to the Signed Tree Head of Certificate Transparency (), applied to a chain in place of a tree.

Security Considerations

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 (). 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.

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.

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.

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 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.

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.

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.

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.

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 (), 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.

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.

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 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 address these cases, and step 1 of applies them before any hash is computed.

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.

Privacy Considerations A record describes the behavior of a person in detail, and that person can be a child. The considerations of apply. This section covers points that are specific to this format.

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 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.

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 .

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.

Limits of Redaction Redaction removes the content of an event. The entry remains and shows that something happened at that time. 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.

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 describe how such correlation can lead to identification. A record SHOULD be treated as personal data whatever identifiers it carries.

Signing Keys The kid of a signed head is the same in every record signed with one key. A key that serves one learner or one device links the records of that learner, whatever their subject identifiers. A key that serves a whole deployment does not.

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.

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

IANA Considerations

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

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.

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 . The expert checks that the URI has the form given in 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:

File Schema URI:

urn:ietf:params:learnlog:file:sequential

Description:

A file that holds one record and grows by appending

Reference:

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

• The URI has the form given in .
• 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:

Event Schema URI:

urn:ietf:params:learnlog:events:assist

Namespace:

assist

Event Types:

help_requested, scaffold_provided

Description:

Help requested and scaffolds provided

Reference:

Event Schema URI:

urn:ietf:params:learnlog:events:dialog

Namespace:

dialog

Event Types:

message

Description:

Turns in an exchange with another party

Reference:

Media Types IANA is requested to register the following media types .

application/learnlog+json

Type name:

application

Subtype name:

learnlog+json

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

binary; see

Security considerations:

See and

Interoperability considerations:

See

Published specification:

This document

Applications that use this media type:

Software that writes, verifies, or analyzes learnlog records

Fragment identifier considerations:

As for application/json

Additional information:

Deprecated alias names for this type:

N/A

Magic number(s):

N/A

File extension(s):

.learnlog

Macintosh file type code(s):

N/A

Person & email address to contact for further information:

See the Author's Address section

Intended usage:

COMMON

Restrictions on usage:

N/A

Author:

See the Author's Address section

Change controller:

IETF

Provisional registration? (standards tree only):

No

application/learnlog+json-seq

Type name:

application

Subtype name:

learnlog+json-seq

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

binary; see

Security considerations:

See and

Interoperability considerations:

See

Published specification:

This document

Applications that use this media type:

Software that writes, verifies, or analyzes learnlog records

Fragment identifier considerations:

As for application/json-seq

Additional information:

Deprecated alias names for this type:

N/A

Magic number(s):

N/A

File extension(s):

.slearnlog

Macintosh file type code(s):

N/A

Person & email address to contact for further information:

See the Author's Address section

Intended usage:

COMMON

Restrictions on usage:

N/A

Author:

See the Author's Address section

Change controller:

IETF

Provisional registration? (standards tree only):

No

References Normative References National Institute of Standards and Technology Informative References Work in Progress IEEE 1EdTech Consortium

Example This appendix shows one record in full. Every hash in it can be recomputed from the text of this document.

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.

Event schema of the example $Event /= event-type<"sim:explanation_filed", SimExplanationFiled> ]]>

A Complete File The file in 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 . Each text is one line, with single spaces between words and no line ending. Texts behind the content and configuration hashes

Entry	Member	Text
4	content_hash	Look for a number that divides both 12 and 16.
4	config_hash	example tutor configuration 7
6	content_hash	Simplifying a ratio means dividing both parts by the same number.
6	config_hash	example chat configuration 3

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.

A complete contained file

Intermediate Values The canonical form of the header is: Its SHA-256 hash is the record hash, which is also the prev_hash of entry 1: The canonical form of the event in entry 2 is: Its hash is the event_hash of entry 2: The canonical form of the object that is hashed for entry 2 is: Its hash is the entry_hash of entry 2:

The Signed Head The head was signed with the private key that matches this public key: The JWK Thumbprint of the key, used as kid, is: The protected header is: The JWS payload is the canonical form of the head: The value of signature in the file is: The private key is not given here, so an implementation cannot reproduce this value. The value can be verified with the public key above.

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. 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.

Canonical Form Check The record above has few values that separate the canonical form of from other compact JSON output with sorted member names. The JSON text in 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.

A JSON text for checking the canonical form

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: The SHA-256 hash of those octets is:

Implementation Status This section records the status of known implementations at the time of writing, as described in . qlm-measure version 0.7.0 (Quantum Learning Machines; TypeScript and Python; Apache 2.0 license; https://github.com/QuantumLearningMachines/qlm-measure) writes and verifies records that it labels schema 0.3. This document was derived from that format. Both chain entries by hash and allow an event to be redacted. Both place consent events in the chain. The differences are:

• The recorder of qlm-measure serializes hashed values with sorted member names. Its documentation lists for schema 0.3 as planned.
• A record has no header. The first entry links to an empty string. No hash covers the studentScopeId member, which names the learner of the record.
• Events carry no salt.
• A record can hold attestations that refer to an entry by version or by hash. The verifier checks that reference and a payload hash. No signature is verified.
• Member names differ. For example, qlm-measure uses version and prevHash where this document uses seq and prev_hash.
• The kind of scaffold is a member of an observation event. No event type exists for a request for help or for a scaffold.

Quantum Learning Machines plans to extend qlm-measure so that it writes records in the format of this document.

Open Issues

• The name of the format is open.
• is an Informational RFC from the Independent Submission stream. A normative reference to it from a Standards Track document is a downward reference. The alternative is to define the canonical form in this document. is Informational as well.
• JSON text sequences follow . JSON objects separated by line feeds are an alternative.
• Signed heads use JWS with ES256. Open points are explicit typing of the JWS, a second algorithm, key discovery, and whether COSE would serve better.
• A defined way to lodge heads with a third party would address and .
• A sequential file holds one record. A server that writes for many learners may want to mix records in one file.
• Every event repeats its session and activity. lets a trace state such values once, as common fields. An equivalent here would have to fit the rule that each event is hashed by itself.
• The assist and dialog namespaces are small. Feedback on a response and questions put to the learner are candidates for generic event types. The values of ScaffoldType may belong in a registry.
• The roles instructor and assistant separate parties by teaching responsibility. Deployments may need finer roles.
• The consent scopes are a starting point.
• A reader ignores members that this document does not define, and outside a header, an event, or a head no hash covers them. A stricter rule may be safer.
• The content_hash and config_hash members carry no salt ().
• A producer cannot yet state in the chain which entries it redacted. Such a statement would let a reader tell a redaction by the producer from one by a later holder ().
• No hash covers the list of event schemas (). The header or an event could carry the list.
• A subject identifier cannot differ by recipient ().
• A record cannot change its hash algorithm. A way to continue a record in a new one may be needed.
• A mapping between learnlog events and xAPI statements.
• A companion format for estimates that refer to entries.