Citation anchor check

citation-anchor-check · version 1.0.0 · Text · free, no key needed

Check a quote anchor (exact text plus prefix/suffix) matches exactly one place in a supplied source version.

Use when you need to: verify text quote selector anchors uniquely · check quote with prefix and suffix context in source · is this quotation ambiguous in the document.

Decide before calling

Read the versioned contract and the supported scope below. Reuse citation-anchor-check@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use citation-anchor-check@1.0.0 for verify text quote selector anchors uniquely. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

verify text quote selector anchors uniquely
check quote with prefix and suffix context in source
is this quotation ambiguous in the document
resolve exact quote anchor to code point offsets
check that the cited sentence exists verbatim
verify annotation anchor against supplied text version
בדיקה שציטוט מופיע במקור פעם אחת בדיוק

Not supported

fetching the source or proving the supplied text is authentic
fuzzy or approximate anchoring (no edit distance)
case folding, whitespace collapsing or Unicode normalization
XPath, CSS or range selectors

Behavior

Implements W3C Web Annotation Data Model (Recommendation 2017-02-23) 4.2.4 TextQuoteSelector, 4.2.5 TextPositionSelector; r68 supplied-text profile 1.0.0; every result carries reference_version.
Checks only the caller-supplied text: authenticity_checked is always false. The cited (source_id, version) must be supplied (unknown_source, version_mismatch with available_versions sorted by code point).
exact (non-empty), prefix and suffix are compared code point for code point with no normalization. Every occurrence of exact is considered, overlapping ones included; prefix must end immediately before it and suffix must start immediately after it (W3C 4.2.4). An omitted or empty prefix/suffix matches anything.
Comparison order: exact_not_found, prefix_mismatch (exact occurs but never after prefix; observed is the text before the first occurrence), suffix_mismatch (observed is the text after the first prefix-matching occurrence), ambiguous_anchor (more than one full match), position_mismatch (claimed_start differs from the unique match).
Positions count Unicode code points from 0 (W3C 4.2.5 convention). A valid result returns match {start, end} of the unique occurrence; match_starts lists at most the first two full-match starts.
claimed_start is optional; omitted means no position is checked.

Input

sources (array of object, required): min items 1; max items 16
citation (object, required)

Output

valid (boolean, required)
reason (one of null, "unknown_source", "version_mismatch", "exact_not_found", "prefix_mismatch", "suffix_mismatch", "ambiguous_anchor", "position_mismatch", required)
first_discrepancy (object or null, required)
match (object or null, required)
authenticity_checked (constant false, required)
reference_version (constant "W3C Web Annotation Data Model (Recommendation 2017-02-23) 4.2.4 TextQuoteSelector, 4.2.5 TextPositionSelector; r68 supplied-text profile 1.0.0", required)

Limits

max input bytes: 1048576
max sources: 16
max text bytes: 524288
max quote bytes: 16384
max context bytes: 1024
max label bytes: 256

Example

Request input:

{
  "sources": [
    {
      "source_id": "doc",
      "version": "2017-02-23",
      "text": "An anotation is not an annotation, but this is an anotation that has some typos."
    }
  ],
  "citation": {
    "source_id": "doc",
    "version": "2017-02-23",
    "selector": {
      "type": "TextQuoteSelector",
      "exact": "anotation",
      "prefix": "this is an ",
      "suffix": " that has some"
    }
  }
}

Response:

{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "match": {
      "start": 50,
      "end": 59
    },
    "authenticity_checked": false,
    "reference_version": "W3C Web Annotation Data Model (Recommendation 2017-02-23) 4.2.4 TextQuoteSelector, 4.2.5 TextPositionSelector; r68 supplied-text profile 1.0.0"
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "citation-anchor-check",
  "version": "1.0.0",
  "input": {
    "sources": [
      {
        "source_id": "doc",
        "version": "2017-02-23",
        "text": "An anotation is not an annotation, but this is an anotation that has some typos."
      }
    ],
    "citation": {
      "source_id": "doc",
      "version": "2017-02-23",
      "selector": {
        "type": "TextQuoteSelector",
        "exact": "anotation",
        "prefix": "this is an ",
        "suffix": " that has some"
      }
    }
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/citation-anchor-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"sources":[{"source_id":"doc","version":"2017-02-23","text":"An anotation is not an annotation, but this is an anotation that has some typos."}],"citation":{"source_id":"doc","version":"2017-02-23","selector":{"type":"TextQuoteSelector","exact":"anotation","prefix":"this is an ","suffix":" that has some"}}}'

The machine-readable contract is at /v1/tools/citation-anchor-check/versions/1.0.0.

CLI

node cli.mjs run citation-anchor-check 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

Citation passage check: Check that a cited start/end span of a supplied source version reads exactly as the quoted passage.
Citation batch check: Check an ordered batch of citations (span+quote or quote anchors) against supplied sources; returns the first failure.
Text sentence offsets: Return UAX #29 sentence spans as start/end offsets in code points, UTF-16 units or UTF-8 bytes, with the ending rule.
Chrf compute: Compute exact chrF (character 6-gram F-beta, Popovic 2015) for hypothesis/reference segments, corpus and per segment.
Citation record normalize: Normalize one CSL 1.0.2 citation record: NFC, whitespace, empty values, DOI wrapper, page dashes, dates; lists changes.
Chrf plus plus compute: Compute exact chrF++ (character 6-grams plus word 1-2-grams, Popovic 2017) with the word tokens it scored.