ClaimSearchResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/greenlitbooks-com/json-schema/greenlitbooks-com-claim-search-result-schema.json",
  "title": "ClaimSearchResult",
  "description": "One matching claim, with why it matched.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/greenlitbooks-com-openapi.json#/components/schemas/ClaimSearchResult",
  "type": "object",
  "properties": {
    "score": {
      "type": "number",
      "description": "Word relevance, comparable with /search scores. 0 when the claim was found by meaning alone."
    },
    "matchedFields": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "matchedTerms": {
      "type": "integer",
      "description": "How many of query.terms this claim's words account for. A claim found by its words accounts for a strict majority of them, so a partial match is visible as one rather than reading as an exact answer."
    },
    "matchedBy": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "words",
          "meaning"
        ]
      },
      "description": "How the claim was found. words: it accounts for most of the query's terms. meaning: its sentence says something close to the query in other words, and shares at least two distinctive words with it. Both is the strongest."
    },
    "similarity": {
      "type": [
        "number",
        "null"
      ],
      "description": "Closeness in meaning between the query and the claim sentence, from 0 to 1. Results are ordered by it when it is present. Null when meaning was unavailable for the request."
    },
    "claim": {
      "$ref": "#/$defs/Claim"
    }
  },
  "$defs": {
    "BookLink": {
      "type": "object",
      "description": "Compact pointer to a book, with its reading-order position in its series.",
      "properties": {
        "slug": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "position": {
          "type": "integer",
          "description": "1-based reading order within the series."
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "apiUrl": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "Citation": {
      "type": "object",
      "description": "The citation for this claim, already written, in the forms people paste. Both carry the fragment URL, so a quote taken from this export attributes itself.",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The fragment the citation points at."
        },
        "text": {
          "type": "string",
          "description": "Ready to paste into prose. The same string the book page renders. It ends with the date the record was last reviewed rather than an access date, because a build-time access date would describe when the page was generated, not when it was read."
        },
        "bibtex": {
          "type": "string",
          "description": "Ready to paste into a .bib file."
        },
        "key": {
          "type": "string",
          "description": "The BibTeX key on its own, for citing in LaTeX."
        }
      }
    },
    "Claim": {
      "type": "object",
      "description": "One quotable claim with a stable citation URL.",
      "properties": {
        "id": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The fragment to cite. Stable: an id is never reworded in place."
        },
        "anchor": {
          "type": "string"
        },
        "chapter": {
          "type": "integer"
        },
        "claim": {
          "type": "string"
        },
        "verbatim": {
          "type": "boolean",
          "description": "True when this is the book's own sentence."
        },
        "basis": {
          "type": "string",
          "enum": [
            "external",
            "argument",
            "method",
            "author-experience"
          ],
          "description": "What kind of statement this is. The four are not interchangeable."
        },
        "basisLabel": {
          "type": "string"
        },
        "quotingRule": {
          "type": "string",
          "description": "How this basis may honestly be quoted."
        },
        "basisNote": {
          "type": "string"
        },
        "citation": {
          "$ref": "#/$defs/Citation"
        },
        "sources": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ClaimSource"
          }
        },
        "book": {
          "$ref": "#/$defs/BookLink"
        }
      }
    },
    "ClaimSource": {
      "type": "object",
      "description": "One external source behind a claim. Both halves are required: what a reader who opens this URL will find, and what the claim would be overreaching to draw from it.",
      "properties": {
        "title": {
          "type": "string"
        },
        "authors": {
          "type": [
            "string",
            "null"
          ]
        },
        "publisher": {
          "type": [
            "string",
            "null"
          ]
        },
        "date": {
          "type": [
            "string",
            "null"
          ],
          "description": "Whatever date the source itself states."
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "establishes": {
          "type": "string"
        },
        "doesNotEstablish": {
          "type": "string"
        },
        "lastChecked": {
          "type": "string",
          "format": "date"
        },
        "checkNote": {
          "type": "string",
          "description": "Present when the check was indirect, naming how it was made."
        }
      }
    }
  }
}