feat: trace annotation body for traced citations; paperspec.traces
A trace follows one citation of a sentence of a citing paper to a passage of the cited paper (spec/18 section 18.5). Minor change: a new body kind, optional properties and two rules, with no valid file made invalid. - annotation schema branch (source, selector, reference, note, verdict, proposer; proposer required for a Software creator); body_kind in sql/store.sql; the note and proposer terms of the JSON-LD context; rules layer.trace.source and layer.trace.target. - paperspec.traces: resolve(annotation, citing_state, cited_state, same_as) gives current, changed, stale, unlinked or misresolved with open and cites; problems, disputes, disputed. - fixtures/records/traces/ on writer2027fixed-ynr7.v3 and vectors/traces.jsonl (29 cases); check.py runs the record checks over both layers; counts, glossary, examples and CHANGELOG updated. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uy4ZYbWRoCdUtWLEfigysY
This commit is contained in:
25 files changed
+966
-50
No files matched your search
+13
-6
@@ -57,14 +57,14 @@ This context defines `kind`, `status`, `audience`, `AnchorSelector` and `anchor`
|
||||
|
||||
## What it defines
|
||||
|
||||
The file defines 25 terms.
|
||||
Twenty-four map to IRIs under `https://paperspec.scient.ing/vocab#`: `format`, `kind`, `status`, `receipt`, `layer`, `audience`, `visibility`, `purpose`, `project`, `docs`, `pin`, `role`, `symbol`, `key`, `verdict`, `reason`, `reference`, `for`, `category`, `generator`, `exercise`, `anchor`, `rights_use` and the class `AnchorSelector`.
|
||||
Four are renamed: `key`, the key of a `symbol` body's symbol, is `sct:symbolKey`, `for` is `sct:questionFor`, `generator` is `sct:generatedBy`, and `rights_use` is `sct:rightsUse`.
|
||||
The twenty-fifth, `total`, maps to `totalItems` in the ActivityStreams namespace.
|
||||
The file defines 27 terms.
|
||||
Twenty-six map to IRIs under `https://paperspec.scient.ing/vocab#`: `format`, `kind`, `status`, `receipt`, `layer`, `audience`, `visibility`, `purpose`, `project`, `docs`, `pin`, `role`, `symbol`, `key`, `verdict`, `reason`, `reference`, `note`, `proposer`, `for`, `category`, `generator`, `exercise`, `anchor`, `rights_use` and the class `AnchorSelector`.
|
||||
Five are renamed: `key`, the key of a `symbol` body's symbol, is `sct:symbolKey`, `for` is `sct:questionFor`, `generator` is `sct:generatedBy`, `proposer`, the tool that found a trace, is `sct:proposedBy`, and `rights_use` is `sct:rightsUse`.
|
||||
The twenty-seventh, `total`, maps to `totalItems` in the ActivityStreams namespace.
|
||||
Two terms carry a type rule.
|
||||
A processor reads `layer` as an IRI, and it always reads `docs` as a set, so a one-element list stays a list.
|
||||
|
||||
The file declares `anchor` and `exercise` as JSON literals (`"@type": "@json"`, a JSON-LD 1.1 feature, which is why the file sets `"@version": 1.1`).
|
||||
The file declares `anchor`, `exercise` and `proposer` as JSON literals (`"@type": "@json"`, a JSON-LD 1.1 feature, which is why the file sets `"@version": 1.1`).
|
||||
A JSON-LD processor then keeps a `scienting-anchor/1` record intact instead of expanding it.
|
||||
An anchor holds hashes (fixed-length fingerprints of text) and a `span`, a pair of character offsets whose order carries meaning.
|
||||
Expansion would drop the anchor's unmapped field names ([JSON-LD 1.1 API, expansion step 13.3](https://www.w3.org/TR/json-ld11-api/#alg-expand-each-key-value)) and would give its arrays no order ([JSON-LD 1.1 §4.3](https://www.w3.org/TR/json-ld11/#sets-and-lists)).
|
||||
@@ -90,6 +90,13 @@ That is the repository's statement; no Web Annotation client has been tested aga
|
||||
The fallback is not always there.
|
||||
Three of the eleven fixture annotations have only an `AnchorSelector` (the section-level question, the `generated` annotation on a figure and the exercise on a table), because the anchor points at a container and has no quote.
|
||||
|
||||
## A body that points at another paper
|
||||
|
||||
A `trace` body ([spec/18 §18.5](../spec/18-layers.md#185-traced-citations)) follows a citation in the annotated sentence to a passage of the cited paper, so its `source` and `selector` name the cited paper, not the annotated one.
|
||||
[`fixtures/records/traces/annotations.jsonl`](../fixtures/records/traces/annotations.jsonl) holds four annotations on the draft `writer2027fixed-ynr7.v3`, which cites the example paper.
|
||||
The Web Annotation context defines `source` and `selector` for a body as it does for a target, so a trace's selector list puts the `AnchorSelector` first and the `TextQuoteSelector` after it, as a target's does.
|
||||
This context adds the rest of the body: `reference`, the reference of the draft that the sentence cites, `note`, `verdict` and `proposer`, which a processor keeps whole, as it keeps an anchor, because its model's hashes and its score are values and not terms.
|
||||
|
||||
## Using the context
|
||||
|
||||
- Writer: Put both URLs (web addresses), in the order shown, in `@context` of `layer.json` and of every line of `annotations.jsonl`. [Chapter 18](../spec/18-layers.md) defines layers (§18.2), annotations (§18.3) and bodies (§18.4).
|
||||
@@ -97,7 +104,7 @@ Three of the eleven fixture annotations have only an `AnchorSelector` (the secti
|
||||
The file `vectors/resolve.jsonl` resolves seventeen anchors against `fixtures/packages/hale2026harmonic-damb` and gives every outcome.
|
||||
- JSON-LD processor: Use a JSON-LD 1.1 processor; the context relies on `@json` and `@version` 1.1.
|
||||
- Checker: `schemas/annotation.schema.json` and `schemas/layer.schema.json` validate the files.
|
||||
`paperspec check` also checks that each annotation's ID derives from its content and that the receipt at `fixtures/records/layer/receipt.json` covers each `confirmed` annotation.
|
||||
`paperspec check` also checks that each annotation's ID derives from its content and that the receipt of its layer, at `fixtures/records/layer/receipt.json` or `fixtures/records/traces/receipt.json`, covers each `confirmed` annotation.
|
||||
|
||||
The traps:
|
||||
|
||||
|
||||
@@ -25,6 +25,11 @@
|
||||
"verdict": "sct:verdict",
|
||||
"reason": "sct:reason",
|
||||
"reference": "sct:reference",
|
||||
"note": "sct:note",
|
||||
"proposer": {
|
||||
"@id": "sct:proposedBy",
|
||||
"@type": "@json"
|
||||
},
|
||||
"for": "sct:questionFor",
|
||||
"category": "sct:category",
|
||||
"generator": "sct:generatedBy",
|
||||
|
||||
Reference in new issue
Block a user