# org.cairnsproto.draft.getReading

> The current reading of a project under its policy, with the inputs a client needs to recompute it: every input record's URI, CID and first-seen epoch, and the beacons its draw claims used.

- Kind: query
- Authority: draft.cairnsproto.org
- Lexicon: 1
- Published by [cairnsproto.org](https://lexicon.garden/identity/did:plc:np7ezqujtsry4bkogisaabul), the NSID's authority

## Links

- [Documentation](https://lexicon.garden/lexicon/did:plc:np7ezqujtsry4bkogisaabul/org.cairnsproto.draft.getReading)
- [Schema JSON](https://lexicon.garden/lexicon/did:plc:np7ezqujtsry4bkogisaabul/org.cairnsproto.draft.getReading/schema.json)
- [Analytics](https://lexicon.garden/lexicon/did:plc:np7ezqujtsry4bkogisaabul/org.cairnsproto.draft.getReading/analytics)

## Query (`org.cairnsproto.draft.getReading`)

Type: query · GET

### Parameters (query string)

- `project` (string · at-uri, required)
- `site` (string): Limit sites to this site key (hex).
  - Constraints: minLength: 64, maxLength: 64

### Output (application/json)

- `beacons` (array, required)
  - `items` (ref)
    - Reference: `#beacon`
- `epoch` (integer, required): The indexer's current epoch.
  - Constraints: minimum: 0
- `exports` (array)
  - `items` (ref)
    - Reference: `#export`
- `gaps` (array, required)
  - `items` (ref)
    - Reference: `#gap`
- `inputRoot` (ref, required)
  - Reference: `org.cairnsproto.draft.defs#hash`
- `inputs` (array, required)
  - `items` (ref)
    - Reference: `#input`
- `policy` (ref, required)
  - Reference: `com.atproto.repo.strongRef`
- `project` (ref, required)
  - Reference: `com.atproto.repo.strongRef`
- `published` (ref): The official repo's state, from the latest import result a maintainer published.
  - Reference: `#published`
- `rejected` (array, required)
  - `items` (ref)
    - Reference: `#rejected`
- `sites` (array, required)
  - `items` (ref)
    - Reference: `#siteReading`
- `sources` (array): One entry per source hash the project covers or its stones trace back to that a source record names, so a frontend can show a source by name instead of hash. Join it to a site's or gap's source hash.
  - `items` (ref)
    - Reference: `#sourceSummary`

## #beacon (`org.cairnsproto.draft.getReading#beacon`)

Type: object

### Properties

- `round` (integer, required)
  - Constraints: minimum: 1
- `signature` (string, required)
  - Constraints: minLength: 96, maxLength: 96

## #candidate (`org.cairnsproto.draft.getReading#candidate`)

Type: object

### Properties

- `agreePpm` (integer, required)
  - Constraints: minimum: 0
- `agreeingSponsors` (integer, required)
  - Constraints: minimum: 0
- `disagreePpm` (integer, required)
  - Constraints: minimum: 0
- `drawnAgreeing` (integer, required)
  - Constraints: minimum: 0
- `high` (integer, required): High bound of the agreement interval, in ppm.
  - Constraints: minimum: 0, maximum: 1000000
- `low` (integer, required): Low bound of the agreement interval, in ppm: support for the share of independent reads that agree on this candidate. It is not a measured accuracy.
  - Constraints: minimum: 0, maximum: 1000000
- `stones` (array, required)
  - `items` (ref)
    - Reference: `com.atproto.repo.strongRef`
- `value` (ref, required): Digest of the canonical value.
  - Reference: `org.cairnsproto.draft.defs#hash`
- `vouched` (boolean): Present and true when a converted stone naming a transform the project vouches for reads this candidate, so its support rests on the maintainer's vouch, not only on independent reads.

## #export (`org.cairnsproto.draft.getReading#export`)

Type: object

### Properties

- `export` (ref, required)
  - Reference: `com.atproto.repo.strongRef`
- `merged` (ref)
  - Reference: `#merge`

## #gap (`org.cairnsproto.draft.getReading#gap`)

Type: object

A site that is not done. A site no stone has reached yet also names its course and the site itself, and a root-course one its source, so a contributor can place the first stone.

### Properties

- `course` (string): Course id, for a root-course site with no stones.
  - Constraints: maxLength: 128
- `reason` (string, required)
  - Constraints: maxLength: 32, knownValues: open | contested | tied | ambiguous | belowExport | unreadable | held | escalated
- `site` (ref, required)
  - Reference: `org.cairnsproto.draft.defs#hash`
- `source` (ref): The source an empty root-course site marks into.
  - Reference: `org.cairnsproto.draft.defs#hash`
- `value` (ref): The site itself, for a site no stone has reached: a root course's whole-source site, or a child site a split course opened.
  - Reference: `org.cairnsproto.draft.defs#site`

## #input (`org.cairnsproto.draft.getReading#input`)

Type: object

### Properties

- `cid` (string · cid, required)
- `seenEpoch` (integer, required)
  - Constraints: minimum: 0
- `uri` (string · at-uri, required)

## #merge (`org.cairnsproto.draft.getReading#merge`)

Type: object

The first maintainer import result holding every file of the export at the same hash.

### Properties

- `commit` (string, required)
  - Constraints: maxLength: 64
- `importResult` (ref, required)
  - Reference: `com.atproto.repo.strongRef`

## #published (`org.cairnsproto.draft.getReading#published`)

Type: object

### Properties

- `commit` (string, required)
  - Constraints: maxLength: 64
- `importResult` (ref, required)
  - Reference: `com.atproto.repo.strongRef`
- `source` (ref, required)
  - Reference: `com.atproto.repo.strongRef`
- `valuesFetched` (boolean, required): Whether the indexer has the import result's values blob. Sites carry no comparison until it does.

## #rejected (`org.cairnsproto.draft.getReading#rejected`)

Type: object

### Properties

- `reason` (string, required)
  - Constraints: maxLength: 1000
- `uri` (string · at-uri, required)

## #siteReading (`org.cairnsproto.draft.getReading#siteReading`)

Type: object

### Properties

- `candidates` (array, required)
  - `items` (ref)
    - Reference: `#candidate`
- `children` (array): With site: the sites whose base builds on this one, sorted by key.
  - `items` (ref)
    - Reference: `org.cairnsproto.draft.defs#hash`
- `course` (string): The id of the project course whose schema the site's schema is.
  - Constraints: maxLength: 128
- `error` (string)
  - Constraints: maxLength: 1000
- `parent` (ref): The site a child site's base builds on.
  - Reference: `org.cairnsproto.draft.defs#hash`
- `published` (string): How the official repo's value compares with the leading candidate.
  - Constraints: maxLength: 32, knownValues: matches | diverges
- `schema` (ref, required)
  - Reference: `org.cairnsproto.draft.defs#hash`
- `site` (ref, required)
  - Reference: `org.cairnsproto.draft.defs#hash`
- `split` (boolean): Whether the leading value is a split, whose parts are child sites in the same course.
- `state` (string, required)
  - Constraints: maxLength: 32, knownValues: open | contested | tied | ambiguous | leading | unreadable | held | escalated
- `stones` (array, required)
  - `items` (ref)
    - Reference: `#stoneStatus`

## #sourceSummary (`org.cairnsproto.draft.getReading#sourceSummary`)

Type: object

A source's MIME type and first URL, from the maintainers' source records before anyone else's, each in URI order. The hash is the identity.

### Properties

- `hash` (ref, required)
  - Reference: `org.cairnsproto.draft.defs#hash`
- `mimeType` (string)
  - Constraints: maxLength: 256
- `url` (string · uri)

## #stoneStatus (`org.cairnsproto.draft.getReading#stoneStatus`)

Type: object

### Properties

- `author` (string · did, required)
- `drawn` (boolean, required)
- `status` (string, required)
  - Constraints: maxLength: 32, knownValues: leading | pebble | tied | withdrawn | attempt | sealed | unsponsored | branched | unreadable | hollow | excluded
- `stone` (ref, required)
  - Reference: `com.atproto.repo.strongRef`
- `witnesses` (array): With site: witnesses naming the stone.
  - `items` (ref)
    - Reference: `#witnessView`

## #witnessView (`org.cairnsproto.draft.getReading#witnessView`)

Type: object

### Properties

- `author` (string · did, required)
- `kind` (string, required)
  - Constraints: maxLength: 32, knownValues: checkResult | judgment | recall
- `verdict` (string): A judgment's verdict.
  - Constraints: maxLength: 64
- `witness` (ref, required)
  - Reference: `com.atproto.repo.strongRef`

## Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "beacon": {
      "properties": {
        "round": {
          "minimum": 1,
          "type": "integer"
        },
        "signature": {
          "maxLength": 96,
          "minLength": 96,
          "type": "string"
        }
      },
      "required": [
        "round",
        "signature"
      ],
      "type": "object"
    },
    "candidate": {
      "properties": {
        "agreePpm": {
          "minimum": 0,
          "type": "integer"
        },
        "agreeingSponsors": {
          "minimum": 0,
          "type": "integer"
        },
        "disagreePpm": {
          "minimum": 0,
          "type": "integer"
        },
        "drawnAgreeing": {
          "minimum": 0,
          "type": "integer"
        },
        "high": {
          "description": "High bound of the agreement interval, in ppm.",
          "maximum": 1000000,
          "minimum": 0,
          "type": "integer"
        },
        "low": {
          "description": "Low bound of the agreement interval, in ppm: support for the share of independent reads that agree on this candidate. It is not a measured accuracy.",
          "maximum": 1000000,
          "minimum": 0,
          "type": "integer"
        },
        "stones": {
          "items": {
            "ref": "com.atproto.repo.strongRef",
            "type": "ref"
          },
          "type": "array"
        },
        "value": {
          "description": "Digest of the canonical value.",
          "ref": "org.cairnsproto.draft.defs#hash",
          "type": "ref"
        },
        "vouched": {
          "description": "Present and true when a converted stone naming a transform the project vouches for reads this candidate, so its support rests on the maintainer's vouch, not only on independent reads.",
          "type": "boolean"
        }
      },
      "required": [
        "value",
        "agreeingSponsors",
        "drawnAgreeing",
        "agreePpm",
        "disagreePpm",
        "low",
        "high",
        "stones"
      ],
      "type": "object"
    },
    "export": {
      "properties": {
        "export": {
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        },
        "merged": {
          "ref": "#merge",
          "type": "ref"
        }
      },
      "required": [
        "export"
      ],
      "type": "object"
    },
    "gap": {
      "description": "A site that is not done. A site no stone has reached yet also names its course and the site itself, and a root-course one its source, so a contributor can place the first stone.",
      "properties": {
        "course": {
          "description": "Course id, for a root-course site with no stones.",
          "maxLength": 128,
          "type": "string"
        },
        "reason": {
          "knownValues": [
            "open",
            "contested",
            "tied",
            "ambiguous",
            "belowExport",
            "unreadable",
            "held",
            "escalated"
          ],
          "maxLength": 32,
          "type": "string"
        },
        "site": {
          "ref": "org.cairnsproto.draft.defs#hash",
          "type": "ref"
        },
        "source": {
          "description": "The source an empty root-course site marks into.",
          "ref": "org.cairnsproto.draft.defs#hash",
          "type": "ref"
        },
        "value": {
          "description": "The site itself, for a site no stone has reached: a root course's whole-source site, or a child site a split course opened.",
          "ref": "org.cairnsproto.draft.defs#site",
          "type": "ref"
        }
      },
      "required": [
        "site",
        "reason"
      ],
      "type": "object"
    },
    "input": {
      "properties": {
        "cid": {
          "format": "cid",
          "type": "string"
        },
        "seenEpoch": {
          "minimum": 0,
          "type": "integer"
        },
        "uri": {
          "format": "at-uri",
          "type": "string"
        }
      },
      "required": [
        "uri",
        "cid",
        "seenEpoch"
      ],
      "type": "object"
    },
    "main": {
      "description": "The current reading of a project under its policy, with the inputs a client needs to recompute it: every input record's URI, CID and first-seen epoch, and the beacons its draw claims used.",
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "beacons": {
              "items": {
                "ref": "#beacon",
                "type": "ref"
              },
              "type": "array"
            },
            "epoch": {
              "description": "The indexer's current epoch.",
              "minimum": 0,
              "type": "integer"
            },
            "exports": {
              "items": {
                "ref": "#export",
                "type": "ref"
              },
              "type": "array"
            },
            "gaps": {
              "items": {
                "ref": "#gap",
                "type": "ref"
              },
              "type": "array"
            },
            "inputRoot": {
              "ref": "org.cairnsproto.draft.defs#hash",
              "type": "ref"
            },
            "inputs": {
              "items": {
                "ref": "#input",
                "type": "ref"
              },
              "type": "array"
            },
            "policy": {
              "ref": "com.atproto.repo.strongRef",
              "type": "ref"
            },
            "project": {
              "ref": "com.atproto.repo.strongRef",
              "type": "ref"
            },
            "published": {
              "description": "The official repo's state, from the latest import result a maintainer published.",
              "ref": "#published",
              "type": "ref"
            },
            "rejected": {
              "items": {
                "ref": "#rejected",
                "type": "ref"
              },
              "type": "array"
            },
            "sites": {
              "items": {
                "ref": "#siteReading",
                "type": "ref"
              },
              "type": "array"
            },
            "sources": {
              "description": "One entry per source hash the project covers or its stones trace back to that a source record names, so a frontend can show a source by name instead of hash. Join it to a site's or gap's source hash.",
              "items": {
                "ref": "#sourceSummary",
                "type": "ref"
              },
              "type": "array"
            }
          },
          "required": [
            "project",
            "policy",
            "epoch",
            "inputRoot",
            "sites",
            "gaps",
            "rejected",
            "inputs",
            "beacons"
          ],
          "type": "object"
        }
      },
      "parameters": {
        "properties": {
          "project": {
            "format": "at-uri",
            "type": "string"
          },
          "site": {
            "description": "Limit sites to this site key (hex).",
            "maxLength": 64,
            "minLength": 64,
            "type": "string"
          }
        },
        "required": [
          "project"
        ],
        "type": "params"
      },
      "type": "query"
    },
    "merge": {
      "description": "The first maintainer import result holding every file of the export at the same hash.",
      "properties": {
        "commit": {
          "maxLength": 64,
          "type": "string"
        },
        "importResult": {
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        }
      },
      "required": [
        "importResult",
        "commit"
      ],
      "type": "object"
    },
    "published": {
      "properties": {
        "commit": {
          "maxLength": 64,
          "type": "string"
        },
        "importResult": {
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        },
        "source": {
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        },
        "valuesFetched": {
          "description": "Whether the indexer has the import result's values blob. Sites carry no comparison until it does.",
          "type": "boolean"
        }
      },
      "required": [
        "importResult",
        "source",
        "commit",
        "valuesFetched"
      ],
      "type": "object"
    },
    "rejected": {
      "properties": {
        "reason": {
          "maxLength": 1000,
          "type": "string"
        },
        "uri": {
          "format": "at-uri",
          "type": "string"
        }
      },
      "required": [
        "uri",
        "reason"
      ],
      "type": "object"
    },
    "siteReading": {
      "properties": {
        "candidates": {
          "items": {
            "ref": "#candidate",
            "type": "ref"
          },
          "type": "array"
        },
        "children": {
          "description": "With site: the sites whose base builds on this one, sorted by key.",
          "items": {
            "ref": "org.cairnsproto.draft.defs#hash",
            "type": "ref"
          },
          "type": "array"
        },
        "course": {
          "description": "The id of the project course whose schema the site's schema is.",
          "maxLength": 128,
          "type": "string"
        },
        "error": {
          "maxLength": 1000,
          "type": "string"
        },
        "parent": {
          "description": "The site a child site's base builds on.",
          "ref": "org.cairnsproto.draft.defs#hash",
          "type": "ref"
        },
        "published": {
          "description": "How the official repo's value compares with the leading candidate.",
          "knownValues": [
            "matches",
            "diverges"
          ],
          "maxLength": 32,
          "type": "string"
        },
        "schema": {
          "ref": "org.cairnsproto.draft.defs#hash",
          "type": "ref"
        },
        "site": {
          "ref": "org.cairnsproto.draft.defs#hash",
          "type": "ref"
        },
        "split": {
          "description": "Whether the leading value is a split, whose parts are child sites in the same course.",
          "type": "boolean"
        },
        "state": {
          "knownValues": [
            "open",
            "contested",
            "tied",
            "ambiguous",
            "leading",
            "unreadable",
            "held",
            "escalated"
          ],
          "maxLength": 32,
          "type": "string"
        },
        "stones": {
          "items": {
            "ref": "#stoneStatus",
            "type": "ref"
          },
          "type": "array"
        }
      },
      "required": [
        "site",
        "schema",
        "state",
        "candidates",
        "stones"
      ],
      "type": "object"
    },
    "sourceSummary": {
      "description": "A source's MIME type and first URL, from the maintainers' source records before anyone else's, each in URI order. The hash is the identity.",
      "properties": {
        "hash": {
          "ref": "org.cairnsproto.draft.defs#hash",
          "type": "ref"
        },
        "mimeType": {
          "maxLength": 256,
          "type": "string"
        },
        "url": {
          "format": "uri",
          "type": "string"
        }
      },
      "required": [
        "hash"
      ],
      "type": "object"
    },
    "stoneStatus": {
      "properties": {
        "author": {
          "format": "did",
          "type": "string"
        },
        "drawn": {
          "type": "boolean"
        },
        "status": {
          "knownValues": [
            "leading",
            "pebble",
            "tied",
            "withdrawn",
            "attempt",
            "sealed",
            "unsponsored",
            "branched",
            "unreadable",
            "hollow",
            "excluded"
          ],
          "maxLength": 32,
          "type": "string"
        },
        "stone": {
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        },
        "witnesses": {
          "description": "With site: witnesses naming the stone.",
          "items": {
            "ref": "#witnessView",
            "type": "ref"
          },
          "type": "array"
        }
      },
      "required": [
        "stone",
        "author",
        "status",
        "drawn"
      ],
      "type": "object"
    },
    "witnessView": {
      "properties": {
        "author": {
          "format": "did",
          "type": "string"
        },
        "kind": {
          "knownValues": [
            "checkResult",
            "judgment",
            "recall"
          ],
          "maxLength": 32,
          "type": "string"
        },
        "verdict": {
          "description": "A judgment's verdict.",
          "maxLength": 64,
          "type": "string"
        },
        "witness": {
          "ref": "com.atproto.repo.strongRef",
          "type": "ref"
        }
      },
      "required": [
        "witness",
        "author",
        "kind"
      ],
      "type": "object"
    }
  },
  "id": "org.cairnsproto.draft.getReading",
  "lexicon": 1
}
```