# net.olamaelcu.livtet.biblio.readingProgress

> A reader's relation to one catalog edition, published from the copy they are holding. Two shapes share this collection: a position record (one per edition and format, its rkey the edition's rkey and the format's slug, rewritten as the reader moves) and an annotation record (one per note, under a TID, rewritten when the note is edited). `createdAt` is when the record was first published — the position's first save, the note's own creation — and `updatedAt` when it last changed. Written by Livtet in the reader's own repo and indexed by the catalog.

- Kind: record
- Record key: any
- Authority: biblio.livtet.olamaelcu.net
- Lexicon: 1
- Published by [biblio.livtet.olamaelcu.net](https://lexicon.garden/identity/did:plc:e2x3ihw2ntxt7pcgzmtu3abi), the NSID's authority

## Links

- [Documentation](https://lexicon.garden/lexicon/did:plc:e2x3ihw2ntxt7pcgzmtu3abi/net.olamaelcu.livtet.biblio.readingProgress)
- [Schema JSON](https://lexicon.garden/lexicon/did:plc:e2x3ihw2ntxt7pcgzmtu3abi/net.olamaelcu.livtet.biblio.readingProgress/schema.json)
- [Analytics](https://lexicon.garden/lexicon/did:plc:e2x3ihw2ntxt7pcgzmtu3abi/net.olamaelcu.livtet.biblio.readingProgress/analytics)

## Record (`net.olamaelcu.livtet.biblio.readingProgress`)

Type: record · key any

### Properties

- `annotation` (ref): The note this record mirrors. A record carries either a `position` or an `annotation`; the rkey is a TID, so a note's record is found through the reader's own database rather than derived.
  - Reference: `#annotation`
- `book` (string · at-uri, required): The catalog edition being read.
- `createdAt` (string · datetime, required): When this record was first published.
- `format` (string, required): The reader's format name as the app's seeded formats table spells it (`Hardcover`, `ePub`, `Audiobook`). It is the reader's own copy, not the edition's merged medium: two readers of one edition can report a print and an audio position against it.
  - Constraints: minLength: 1, maxGraphemes: 40
- `identifier` (ref): The product identifier this position's `total` came from; absent when the total came from the edition record.
  - Reference: `#identifier`
- `position` (ref): The reading position. Present on a position record, absent on an annotation record.
  - Reference: `#position`
- `updatedAt` (string · datetime, required): When the reader last moved to this position, or last edited this note.

## #annotation (`net.olamaelcu.livtet.biblio.readingProgress#annotation`)

Type: object

One note taken while reading, mirrored from the reader's own database. `id` is the note's id there, so an edit rewrites the same record instead of appending one.

### Properties

- `color` (string): The highlight colour, as the reader's app spells it.
  - Constraints: maxLength: 32
- `id` (string, required): The note's id in the reader's database.
  - Constraints: maxLength: 128
- `locator` (string): Where in the copy the note sits: a printed page, a chapter, a CFI.
  - Constraints: maxLength: 512
- `pageNumber` (integer)
  - Constraints: minimum: 1
- `quote` (string): The passage the note is attached to.
  - Constraints: maxGraphemes: 2000
- `text` (string, required)
  - Constraints: maxGraphemes: 10000

## #identifier (`net.olamaelcu.livtet.biblio.readingProgress#identifier`)

Type: object

The catalog identifier a total belongs to, such as the print ISBN-13 whose page count `position.total` holds. The edition record's own page count and duration are separate rank winners over these claims, so without this a consumer cannot tell which product a total describes.

### Properties

- `issuer` (string, required): The identifier's issuing scheme, as the catalog spells it (`isbn13`, `isbn10`, `asin`).
- `value` (string, required): The identifier value as issued.

## #position (`net.olamaelcu.livtet.biblio.readingProgress#position`)

Type: object

The position, on the unit's own scale. `per_mille` is tenths of a percent (0–1000); `page` and `virtual_page` are counts; `timestamp` is seconds; `chapter` is the whole chapter number, with any fraction in `locator`; `cfi` is not a scale, so the CFI rides in `locator` and `value` is 0.

### Properties

- `locator` (string): The precise position the integer rounds off: an EPUB CFI, a printed page label, or a clock time.
  - Constraints: maxLength: 512
- `total` (integer): The whole in the same unit: a page count (`identifier`'s claim), a chapter count (the edition's), or a duration in seconds (the audio claim's). Absent when no extent is known.
  - Constraints: minimum: 1
- `unit` (string, required)
  - Constraints: knownValues: per_mille | page | virtual_page | timestamp | chapter | cfi
- `value` (integer, required): The position in `unit`. Only `per_mille` has a fixed range (0–1000).
  - Constraints: minimum: 0

## Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "annotation": {
      "description": "One note taken while reading, mirrored from the reader's own database. `id` is the note's id there, so an edit rewrites the same record instead of appending one.",
      "properties": {
        "color": {
          "description": "The highlight colour, as the reader's app spells it.",
          "maxLength": 32,
          "type": "string"
        },
        "id": {
          "description": "The note's id in the reader's database.",
          "maxLength": 128,
          "type": "string"
        },
        "locator": {
          "description": "Where in the copy the note sits: a printed page, a chapter, a CFI.",
          "maxLength": 512,
          "type": "string"
        },
        "pageNumber": {
          "minimum": 1,
          "type": "integer"
        },
        "quote": {
          "description": "The passage the note is attached to.",
          "maxGraphemes": 2000,
          "type": "string"
        },
        "text": {
          "maxGraphemes": 10000,
          "type": "string"
        }
      },
      "required": [
        "id",
        "text"
      ],
      "type": "object"
    },
    "identifier": {
      "description": "The catalog identifier a total belongs to, such as the print ISBN-13 whose page count `position.total` holds. The edition record's own page count and duration are separate rank winners over these claims, so without this a consumer cannot tell which product a total describes.",
      "properties": {
        "issuer": {
          "description": "The identifier's issuing scheme, as the catalog spells it (`isbn13`, `isbn10`, `asin`).",
          "type": "string"
        },
        "value": {
          "description": "The identifier value as issued.",
          "type": "string"
        }
      },
      "required": [
        "issuer",
        "value"
      ],
      "type": "object"
    },
    "main": {
      "description": "A reader's relation to one catalog edition, published from the copy they are holding. Two shapes share this collection: a position record (one per edition and format, its rkey the edition's rkey and the format's slug, rewritten as the reader moves) and an annotation record (one per note, under a TID, rewritten when the note is edited). `createdAt` is when the record was first published — the position's first save, the note's own creation — and `updatedAt` when it last changed. Written by Livtet in the reader's own repo and indexed by the catalog.",
      "key": "any",
      "record": {
        "properties": {
          "annotation": {
            "description": "The note this record mirrors. A record carries either a `position` or an `annotation`; the rkey is a TID, so a note's record is found through the reader's own database rather than derived.",
            "ref": "#annotation",
            "type": "ref"
          },
          "book": {
            "description": "The catalog edition being read.",
            "format": "at-uri",
            "type": "string"
          },
          "createdAt": {
            "description": "When this record was first published.",
            "format": "datetime",
            "type": "string"
          },
          "format": {
            "description": "The reader's format name as the app's seeded formats table spells it (`Hardcover`, `ePub`, `Audiobook`). It is the reader's own copy, not the edition's merged medium: two readers of one edition can report a print and an audio position against it.",
            "maxGraphemes": 40,
            "minLength": 1,
            "type": "string"
          },
          "identifier": {
            "description": "The product identifier this position's `total` came from; absent when the total came from the edition record.",
            "ref": "#identifier",
            "type": "ref"
          },
          "position": {
            "description": "The reading position. Present on a position record, absent on an annotation record.",
            "ref": "#position",
            "type": "ref"
          },
          "updatedAt": {
            "description": "When the reader last moved to this position, or last edited this note.",
            "format": "datetime",
            "type": "string"
          }
        },
        "required": [
          "book",
          "format",
          "createdAt",
          "updatedAt"
        ],
        "type": "object"
      },
      "type": "record"
    },
    "position": {
      "description": "The position, on the unit's own scale. `per_mille` is tenths of a percent (0–1000); `page` and `virtual_page` are counts; `timestamp` is seconds; `chapter` is the whole chapter number, with any fraction in `locator`; `cfi` is not a scale, so the CFI rides in `locator` and `value` is 0.",
      "properties": {
        "locator": {
          "description": "The precise position the integer rounds off: an EPUB CFI, a printed page label, or a clock time.",
          "maxLength": 512,
          "type": "string"
        },
        "total": {
          "description": "The whole in the same unit: a page count (`identifier`'s claim), a chapter count (the edition's), or a duration in seconds (the audio claim's). Absent when no extent is known.",
          "minimum": 1,
          "type": "integer"
        },
        "unit": {
          "knownValues": [
            "per_mille",
            "page",
            "virtual_page",
            "timestamp",
            "chapter",
            "cfi"
          ],
          "type": "string"
        },
        "value": {
          "description": "The position in `unit`. Only `per_mille` has a fixed range (0–1000).",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "unit",
        "value"
      ],
      "type": "object"
    }
  },
  "id": "net.olamaelcu.livtet.biblio.readingProgress",
  "lexicon": 1
}
```
