{
  "openapi": "3.0.3",
  "info": {
    "title": "licscan",
    "version": "0.11.0",
    "description": "Software license scanning: a repository or an uploaded tree is scanned as a job, a single file or a snippet is answered inline. Every /v1 endpoint takes `Authorization: Bearer <token>`; /healthz does not. Ids are SPDX license ids, the `*-VERSIONLESS` pseudo-labels for a family named without a version, or `LicenseRef-*` ids under the licscan mode; the scancode mode reports as ScanCode does, with its catalogue's keys and its versions (see LicenseRefMode)."
  },
  "servers": [{"url": "/"}],
  "security": [{"bearer": []}],
  "paths": {
    "/v1/scans": {
      "post": {
        "summary": "Scan a repository",
        "description": "Clones a public GitHub repository at one ref and scans it. Returns the job at once; poll it at /v1/scans/{id}.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["repo"],
                "additionalProperties": false,
                "properties": {
                  "repo": {"type": "string", "description": "owner/name or a github.com URL", "example": "aws/aws-sdk-go-v2"},
                  "ref": {"type": "string", "description": "Branch or tag; the default branch when omitted.", "example": "v1.45.1"},
                  "licenseref": {"$ref": "#/components/schemas/LicenseRefMode"},
                  "follow_external_references": {"$ref": "#/components/schemas/FollowExternalReferences"},
                  "concept_keys": {"$ref": "#/components/schemas/ConceptKeys"},
                  "window_cache": {"$ref": "#/components/schemas/WindowCache"},
                  "tagger": {"$ref": "#/components/schemas/Tagger"},
                  "copyrights": {"$ref": "#/components/schemas/Copyrights"},
                  "licenses": {"$ref": "#/components/schemas/Licenses"},
                  "license_categories": {"$ref": "#/components/schemas/LicenseCategories"}
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted and queued.",
            "headers": {"Location": {"description": "/v1/scans/{id}", "schema": {"type": "string"}}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "429": {"$ref": "#/components/responses/AtCapacity"}
        }
      }
    },
    "/v1/scans/tarball": {
      "post": {
        "summary": "Scan an uploaded .tar.gz",
        "description": "Unpacks the archive and scans it as a tree, exactly as a clone is scanned, so a file that points at its sibling LICENSE resolves against it. The same job document and states as a repository scan.",
        "parameters": [
          {"name": "name", "in": "query", "description": "The archive's name, for the job and the report. A multipart upload's filename is used when this is absent.", "schema": {"type": "string"}, "example": "tree.tar.gz"},
          {"$ref": "#/components/parameters/LicenseRef"},
          {"$ref": "#/components/parameters/FollowExternalReferences"},
          {"$ref": "#/components/parameters/ConceptKeys"},
          {"$ref": "#/components/parameters/WindowCache"},
          {"$ref": "#/components/parameters/Tagger"},
          {"$ref": "#/components/parameters/Copyrights"},
          {"$ref": "#/components/parameters/Licenses"},
          {"$ref": "#/components/parameters/LicenseCategories"}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/gzip": {"schema": {"type": "string", "format": "binary"}},
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {"file": {"type": "string", "format": "binary", "description": "The archive."}}
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted and queued.",
            "headers": {"Location": {"description": "/v1/scans/{id}", "schema": {"type": "string"}}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "413": {"description": "Larger than the server's archive limit (1 GiB by default).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "429": {"$ref": "#/components/responses/AtCapacity"},
          "501": {"$ref": "#/components/responses/NotConfigured"}
        }
      }
    },
    "/v1/scans/{id}": {
      "get": {
        "summary": "A scan's state",
        "parameters": [{"$ref": "#/components/parameters/ScanID"}],
        "responses": {
          "200": {"description": "The job.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/v1/scans/{id}/result": {
      "get": {
        "summary": "A finished scan's report",
        "description": "The summary by default; the per-file answers with files=true; ScanCode's document shape with format=scancode.",
        "parameters": [
          {"$ref": "#/components/parameters/ScanID"},
          {"name": "files", "in": "query", "description": "true includes every file's answers.", "schema": {"type": "string", "enum": ["true"]}},
          {"name": "format", "in": "query", "description": "scancode renders ScanCode's JSON shape, per-file detections always included.", "schema": {"type": "string", "enum": ["scancode"]}},
          {"name": "text", "in": "query", "description": "With format=scancode, true includes each detection's matched text.", "schema": {"type": "string", "enum": ["true"]}}
        ],
        "responses": {
          "200": {"description": "The report.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Report"}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"description": "The scan has not finished, or failed; the error says which.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
        }
      }
    },
    "/v1/files": {
      "post": {
        "summary": "Answer one file inline",
        "description": "The body is the file's content. The path matters: the rules key off it (LICENSE is read whole, package.json goes to the manifest parser, a .c file's comments are found by its syntax). A pointer such as \"See LICENSE\" cannot be followed here; upload a tree for that.",
        "parameters": [
          {"name": "path", "in": "query", "required": true, "description": "The file's path within its project.", "schema": {"type": "string"}, "example": "LICENSE"},
          {"$ref": "#/components/parameters/LicenseRef"},
          {"$ref": "#/components/parameters/FollowExternalReferences"},
          {"$ref": "#/components/parameters/ConceptKeys"},
          {"$ref": "#/components/parameters/WindowCache"},
          {"$ref": "#/components/parameters/Tagger"},
          {"$ref": "#/components/parameters/Copyrights"},
          {"$ref": "#/components/parameters/Licenses"},
          {"$ref": "#/components/parameters/LicenseCategories"}
        ],
        "requestBody": {
          "required": true,
          "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary", "description": "At most 10 MiB."}}}
        },
        "responses": {
          "200": {"description": "The file's answer.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FileAnswer"}}}},
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "413": {"description": "Larger than 10 MiB.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "501": {"$ref": "#/components/responses/NotConfigured"},
          "503": {"$ref": "#/components/responses/Busy"},
          "504": {"$ref": "#/components/responses/TimedOut"}
        }
      }
    },
    "/v1/classify": {
      "post": {
        "summary": "What the model alone makes of a snippet",
        "description": "Skips every rule before the model, so it answers a different question from /v1/files: use it to see what the last stage would say. One snippet as the raw body, or up to 64 as JSON.",
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {"schema": {"type": "string"}, "example": "Released under the MIT license."},
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "texts": {"type": "array", "maxItems": 64, "items": {"type": "string"}},
                  "text": {"type": "string"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per snippet, the model's answers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model": {"type": "string"},
                    "results": {"type": "array", "items": {"type": "array", "items": {"$ref": "#/components/schemas/Detection"}}},
                    "note": {"type": "string"}
                  }
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "413": {"description": "Larger than 1 MiB.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "501": {"$ref": "#/components/responses/NotConfigured"},
          "503": {"$ref": "#/components/responses/Busy"},
          "504": {"$ref": "#/components/responses/TimedOut"}
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Liveness",
        "description": "Unauthenticated, for the kubelet's probes; discloses nothing.",
        "security": [],
        "responses": {
          "200": {
            "description": "The service is up.",
            "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "example": "ok"}}}}}
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {"type": "http", "scheme": "bearer", "description": "The token the service was started with (-auth-token, or the chart's auth.token)."}
    },
    "parameters": {
      "ScanID": {"name": "id", "in": "path", "required": true, "description": "The job id returned on submission.", "schema": {"type": "string"}},
      "LicenseRef": {"name": "licenseref", "in": "query", "description": "none, licscan or scancode; the server's default when omitted.", "schema": {"$ref": "#/components/schemas/LicenseRefMode"}},
      "FollowExternalReferences": {"name": "follow_external_references", "in": "query", "description": "true or false, in scancode mode only; the server's default, which follows, when omitted. See FollowExternalReferences.", "schema": {"$ref": "#/components/schemas/FollowExternalReferences"}},
      "ConceptKeys": {"name": "concept_keys", "in": "query", "description": "true or false, in scancode mode only; the server's default, which writes none unless the server was started with -concept-keys, when omitted. See ConceptKeys.", "schema": {"$ref": "#/components/schemas/ConceptKeys"}},
      "WindowCache": {"name": "window_cache", "in": "query", "description": "false reads every window with the model, past the tagger's window cache; true or omitted reads through it. See WindowCache.", "schema": {"$ref": "#/components/schemas/WindowCache"}},
      "Tagger": {"name": "tagger", "in": "query", "description": "false reads with the rules alone; true or omitted lets the model answer what they leave. See Tagger.", "schema": {"$ref": "#/components/schemas/Tagger"}},
      "Copyrights": {"name": "copyrights", "in": "query", "description": "true reads each file's copyright statements and their holders too; false or omitted does not. See Copyrights.", "schema": {"$ref": "#/components/schemas/Copyrights"}},
      "Licenses": {"name": "licenses", "in": "query", "description": "false leaves the license scan out, the copyright scan alone; it needs copyrights=true. See Licenses.", "schema": {"$ref": "#/components/schemas/Licenses"}},
      "LicenseCategories": {"name": "license_categories", "in": "query", "description": "true gives each license its category in LicenseDB's catalogue; false or omitted does not. See LicenseCategories.", "schema": {"$ref": "#/components/schemas/LicenseCategories"}}
    },
    "responses": {
      "BadRequest": {"description": "The request is malformed, names an unknown or unavailable licenseref mode, asks to follow external references or for concept keys in a mode other than scancode, leaves the license scan out without asking for copyrights, or asks for license categories where the server holds no catalogue or the license scan is left out.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "Unauthorized": {"description": "No bearer token, or the wrong one.", "headers": {"WWW-Authenticate": {"schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "NotFound": {"description": "No such scan: an unknown id, or one evicted after its results were kept long enough.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "AtCapacity": {"description": "Refused rather than queued: every worker busy and the queue full. Retry after the Retry-After header's seconds.", "headers": {"Retry-After": {"schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "NotConfigured": {"description": "This server was started without the feature.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "Busy": {"description": "No classifier available right now.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "TimedOut": {"description": "Classification timed out.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
    },
    "schemas": {
      "LicenseRefMode": {
        "type": "string",
        "enum": ["spdx", "licscan", "scancode"],
        "description": "What to answer for a license no SPDX id fits. spdx: nothing -- SPDX ids and the *-VERSIONLESS labels of a family named without a version alone (named none until 2026-10-17; none is still accepted, and answered and reported as spdx). licscan: ScanCode's LicenseRef-scancode-* id where LicenseDB knows the name or the text, else LicenseRef-licscan-unknown-<the name read>. scancode: what ScanCode reports -- the catalogue's keys without the LicenseRef-scancode- prefix (ms-nuget), unknown for a license the catalogue lacks, which loses the name, and for a family named without a version the version ScanCode's convention gives it (a GPL: GPL-1.0-or-later; an LGPL: LGPL-2.1-or-later where the text says Lesser, else LGPL-2.0-or-later; BSD: BSD-3-Clause), a version the text does not state. A family ScanCode has no key for (the MPL, the OFL, the Creative Commons licenses named without a version) is not reported, as ScanCode reports none (2026-10-17; it kept its *-VERSIONLESS label until then). format=scancode restores the prefix in its SPDX fields."
      },
      "FollowExternalReferences": {
        "type": "boolean",
        "description": "scancode mode only: answer a URL naming another project's license file -- a GitHub LICENSE, NuGet's licenseUrl, a Microsoft fwlink -- with what ScanCode's rule for that URL records, as ScanCode does. The file itself states nothing about that license, so no other mode follows one; true in another mode is refused. On by default in scancode mode (the server's -follow-external-references). A job echoes what it asked; a report and a file answer say what was done, and are absent outside scancode mode."
      },
      "ConceptKeys": {
        "type": "boolean",
        "description": "scancode mode only: write ScanCode's concept keys, its keys for what a text is rather than which license it names -- proprietary-license, unknown-license-reference, public-domain, unknown-spdx, other-permissive, free-unknown, ... -- as ScanCode does. Read off ScanCode's own rules for them on a text nothing else answered, a tag naming no SPDX id (unknown-spdx), a public-domain dedication and the Linux kernel's \"Proprietary\" module license. None of them is a license, so no other mode writes one; true in another mode is refused. Off, such a text is silent, a tag naming no SPDX id declares nothing and a dedication is PUBLIC-DOMAIN. Off by default (the server's -concept-keys, the chart's conceptKeys). A job echoes what it asked; a report and a file answer say what was done, and are absent outside scancode mode."
      },
      "WindowCache": {
        "type": "boolean",
        "description": "Every mode: whether the tagger answers a window of text it has read before -- in this scan or an earlier one; the service keeps the cache across requests -- from its window cache. false reads every window with the model and adds none to the cache, for timing tests: the cache changes no answer, only the tagger's time (Stats.tagger_windows_cached). A job echoes what it asked; a report and a file answer say what was done, and are absent where the server keeps no cache."
      },
      "Tagger": {
        "type": "boolean",
        "description": "Every mode: whether the model answers the texts the rules leave. false reads with the rules alone, as a server started without a model reads -- the report then names its model go-rules-only, and no window is read, so window_cache says nothing; it saves the model's time, not its memory. Omitted, or true, the model answers where the server has one. A job echoes what it asked; a report and a file answer say what was done, and are absent where the server has no model."
      },
      "Copyrights": {
        "type": "boolean",
        "description": "Every mode, off by default: read each file's copyright statements and the parties they name (holders), from the file's bytes as stored -- UTF-16 by its byte-order mark, a legacy single-byte encoding where the file is not UTF-8 -- with every name kept in its own script and letters. In none and licscan mode each statement is a structured Copyright; in scancode mode, ScanCode's shape: the statement as `copyright`, the file's holders in its `holders` list, as format=scancode writes them. A file holding a statement and no license has a record for it. A job echoes what it asked, and a report says it ran one."
      },
      "Licenses": {
        "type": "boolean",
        "description": "false leaves the license scan out, so the copyright scan runs alone: no span is cut, no classifier runs, and the model is none. It needs copyrights true -- otherwise there is nothing to scan, and the request is refused. Omitted, or true, the license scan runs."
      },
      "LicenseCategories": {
        "type": "boolean",
        "description": "Every mode, off by default: give each license the category ScanCode's LicenseDB catalogue classes it in -- Permissive, Copyleft, Copyleft Limited, Proprietary Free, Commercial, Non-Commercial, Source-available, Free Restricted, Patent License, Public Domain, CLA, Unstated License -- as License.category, and the report a count of files per category (category_summary). An SPDX id takes the catalogue's entry for it, a catalogue id (licscan mode) or key (scancode mode) its entry, a family named without a version (GPL-only-VERSIONLESS) its members' category where they all share one, and a name the catalogue lacks none. The category is ScanCode's, read off names.json; the licenses found are unchanged, and so is format=scancode. Refused where the server's data directory holds no catalogue, and beside licenses=false. A job echoes what it asked; a report and a file answer say it was done."
      },
      "Copyright": {
        "type": "object",
        "description": "One copyright statement. none and licscan mode: `statement`, its `holders` each with the years it gives them, `years`, and `read_from`. scancode mode: ScanCode's `copyright` and lines, the holders in the file's `holders` list. Both carry byte offsets into the file as stored.",
        "properties": {
          "statement": {"type": "string", "description": "The statement's words as the file writes them, comment markers, markup and entities read through: \"Copyright (c) 2001 Jürgen Müller\". 'All rights reserved' is no part of it."},
          "copyright": {"type": "string", "description": "scancode mode: the statement, as ScanCode's key names it."},
          "holders": {"type": "array", "items": {"$ref": "#/components/schemas/Holder"}, "description": "The parties the statement names, as written, e-mails and URLs left out: one for names written plainly under one year range (\"Jean-loup Gailly, Mark Adler\"), several where each has its own years or address."},
          "years": {"type": "string", "description": "The statement's years as written: \"2011-2014, 2016\", \"2016-present\", a template's YEAR."},
          "start_line": {"type": "integer"},
          "end_line": {"type": "integer"},
          "start_offset": {"type": "integer", "description": "The statement's first byte in the file as stored, 0-based."},
          "end_offset": {"type": "integer", "description": "One past its last byte."},
          "read_from": {"type": "string", "enum": ["notice", "spdx-tag", "font", "binary"], "description": "How it was read: a statement written in the text; a REUSE SPDX-FileCopyrightText tag; a font's name table, which has no place among the file's bytes, so its offsets are 0; or one of a binary file's strings, such as a Windows version resource's LegalCopyright or a compiled message catalogue's header."}
        }
      },
      "Holder": {"type": "object", "properties": {"name": {"type": "string"}, "years": {"type": "string"}}},
      "HolderSpan": {
        "type": "object",
        "description": "scancode mode: a holder as ScanCode lists it, one entry per statement naming it, with the statement's lines.",
        "properties": {"holder": {"type": "string"}, "start_line": {"type": "integer"}, "end_line": {"type": "integer"}}
      },
      "HolderSummary": {
        "type": "object",
        "description": "One holder across the tree, compared with case and punctuation folded: the name as first written, the files whose statements name it, and the years they give it, merged.",
        "properties": {"holder": {"type": "string"}, "files": {"type": "integer"}, "years": {"type": "string", "example": "2011-2016, 2019"}}
      },
      "Stats": {
        "type": "object",
        "description": "What a scan looked at, and what reached each half of the pipeline.",
        "properties": {
          "files_seen": {"type": "integer"},
          "files_skipped": {"type": "integer"},
          "files_read": {"type": "integer"},
          "files_binary": {"type": "integer"},
          "files_font": {"type": "integer"},
          "files_anchored": {"type": "integer"},
          "bytes_read": {"type": "integer"},
          "spans_emitted": {"type": "integer", "description": "License-bearing spans the scanner emitted."},
          "spans_filtered": {"type": "integer", "description": "Spans the server's span filter dropped before they were emitted."},
          "files_answered": {"type": "integer", "description": "Files with a license or a license exception."},
          "files_copyright": {"type": "integer", "description": "With copyrights: the files holding a copyright statement."},
          "copyrights": {"type": "integer", "description": "With copyrights: the statements."},
          "texts_distinct": {"type": "integer", "description": "Distinct texts among the spans: the spans grouped by their text as written, each read once by the rules."},
          "spans_to_tagger": {"type": "integer", "description": "Spans whose text the rules left for the tagger; 0 without a model."},
          "texts_to_tagger": {"type": "integer", "description": "Their distinct texts."},
          "spans_tagger_read": {"type": "integer", "description": "Of those, the spans whose text the tagger read, past its gates (the rest it did not read)."},
          "texts_tagger_read": {"type": "integer", "description": "Their distinct texts."},
          "tagger_windows": {"type": "integer", "description": "The windows the tagger read of those texts."},
          "tagger_windows_cached": {"type": "integer", "description": "Of those, the windows the window cache answered, or a repeat of a window earlier in the same pass: the model ran the rest."},
          "files_unpacked": {"type": "integer", "description": "An upload only."},
          "entries_skipped": {"type": "integer", "description": "An upload only: links and devices, not extracted."},
          "entries_unread": {"type": "integer", "description": "An upload only: files the scan never opens by name, discarded unwritten."}
        }
      },
      "Timings": {
        "type": "object",
        "description": "Where the wall clock went, in milliseconds. classify_ms runs from the first span to the last answer, so it holds scan_ms, rules_ms and tagger_ms, one after the other, and reading the spans and aggregating the answers by file.",
        "properties": {
          "clone_ms": {"type": "integer", "description": "The clone; for an upload, the unpacking; for a single file, writing it to a workspace."},
          "scan_ms": {"type": "integer", "description": "The scanner emitting spans."},
          "classify_ms": {"type": "integer"},
          "rules_ms": {"type": "integer", "description": "The rules over every distinct text."},
          "tagger_ms": {"type": "integer", "description": "The tagger over the texts the rules left; 0 without a model or where the rules answered everything."},
          "total_ms": {"type": "integer"}
        }
      },
      "Error": {"type": "object", "properties": {"error": {"type": "string"}}},
      "Job": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "source": {"type": "string", "enum": ["git", "upload"]},
          "repo": {"type": "string"},
          "ref": {"type": "string"},
          "state": {"type": "string", "enum": ["queued", "cloning", "extracting", "scanning", "classifying", "succeeded", "failed"]},
          "error": {"type": "string", "description": "Why the scan failed."},
          "submitted": {"type": "string", "format": "date-time"},
          "started": {"type": "string", "format": "date-time"},
          "finished": {"type": "string", "format": "date-time"},
          "commit": {"type": "string", "description": "The commit scanned; absent for an upload."},
          "filename": {"type": "string"},
          "archive_bytes": {"type": "integer"},
          "licenseref": {"$ref": "#/components/schemas/LicenseRefMode"},
          "follow_external_references": {"$ref": "#/components/schemas/FollowExternalReferences"},
          "concept_keys": {"$ref": "#/components/schemas/ConceptKeys"},
          "window_cache": {"$ref": "#/components/schemas/WindowCache"},
          "tagger": {"$ref": "#/components/schemas/Tagger"},
          "copyrights": {"$ref": "#/components/schemas/Copyrights"},
          "licenses": {"$ref": "#/components/schemas/Licenses"},
          "license_categories": {"$ref": "#/components/schemas/LicenseCategories"}
        }
      },
      "License": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "example": "Apache-2.0"},
          "score": {"type": "number", "description": "1.0 a rule, 0.9 a pointer resolved to its target, 0.8 a LicenseRef name, anything else the model."},
          "start_line": {"type": "integer", "description": "The first line of the evidence, 1-based: the words the stage that answered read, where it located them (located), or the span the answer came from."},
          "end_line": {"type": "integer", "description": "Its last line, inclusive."},
          "matched_text": {"type": "string", "description": "The evidence's text: the words that decided the answer where located -- an SPDX tag, a trove classifier, a manifest's licence field, a notice, a grant clause, a licence URL, the name the model read -- and the span's opening otherwise, 400 characters at most either way."},
          "start_offset": {"type": "integer", "description": "The evidence's first byte in the file as the scanner read it (a UTF-16 file decoded, a font's licence record), 0-based."},
          "end_offset": {"type": "integer", "description": "One past its last byte."},
          "located": {"type": "boolean", "description": "The stage that answered located the words it read, and the evidence is those words; absent, the evidence is the span the answer came from -- a licence text written out, or a stage that keeps no place."},
          "category": {"type": "string", "example": "Permissive", "description": "With license_categories: the license's category in LicenseDB's catalogue (LicenseCategories); absent where the catalogue does not class it, or where none was asked."}
        }
      },
      "Detection": {"type": "object", "properties": {"id": {"type": "string"}, "score": {"type": "number"}}},
      "FileResult": {
        "type": "object",
        "properties": {
          "path": {"type": "string"},
          "licenses": {"type": "array", "items": {"$ref": "#/components/schemas/License"}},
          "exceptions": {"type": "array", "items": {"type": "string"}, "description": "License exceptions declared beside the license, e.g. Classpath-exception-2.0."},
          "exception_licenses": {"type": "array", "items": {"$ref": "#/components/schemas/ExceptionLicense"}, "description": "The licenses the file's stated exceptions modify, as each exception's own words name them: one entry per license an exception names. Beside `exceptions`, which it leaves as it is, and never a license of the file's own -- GCC's runtime exception names \"the GNU General Public License, version 3\" whatever the file it rides grants, which `licenses` and `expression` state. An exception whose words name no license (Asterisk's, GNOME's examples') has no entry, and neither has one of ScanCode's catalogue."},
          "expression": {"type": "string", "description": "The SPDX license expression the file states, in SPDX 2.3's syntax -- e.g. `MIT OR Apache-2.0`, `GPL-2.0-only WITH Classpath-exception-2.0` -- present only where the file writes one: an SPDX-License-Identifier tag, or a manifest field that holds an expression (or a list its format defines as a choice). Never inferred: `licenses` are the licenses found, a list with no relation among its ids; this is the relation, where the file states it. Its ids are always `licenses`' and its exceptions `exceptions`'."},
          "third_party": {"type": "boolean", "description": "The file is a document of other components' notices (THIRD-PARTY-NOTICES and its kin, by name), read one component at a time: its licenses are what the project bundles, not the project's own."},
          "copyrights": {"type": "array", "items": {"$ref": "#/components/schemas/Copyright"}, "description": "With copyrights: the file's copyright statements, in the shape its mode writes. Absent where it holds none."},
          "holders": {"type": "array", "items": {"$ref": "#/components/schemas/HolderSpan"}, "description": "With copyrights, in scancode mode: ScanCode's holders list."}
        }
      },
      "ExceptionLicense": {
        "type": "object",
        "description": "A license a stated exception's own words say it modifies, read off the exception's text and never off the name SPDX or ScanCode gives it: the Classpath exception's words name \"the GNU General Public License\" and no version.",
        "required": ["exception", "family"],
        "properties": {
          "exception": {"type": "string", "description": "The exception, as `exceptions` writes it."},
          "family": {"type": "string", "description": "The license family as SPDX's ids begin it: GPL, LGPL, AGPL, Apache, CPL, QPL, BSD, wxWindows."},
          "version": {"type": "string", "description": "The version the exception's words state, e.g. 3.0; absent where they state none."},
          "scope": {"type": "string", "enum": ["only", "or-later"], "description": "The scope the words state, which they rarely do -- OpenJDK's assembly exception says version 2 only; absent where they state none."},
          "id": {"type": "string", "description": "The SPDX license id the words name whole -- Apache-2.0 for the LLVM exception, GPL-2.0-only for OpenJDK's; absent where they leave something out: a GNU license's version without a scope is no id."}
        }
      },
      "FileAnswer": {
        "type": "object",
        "properties": {
          "path": {"type": "string"},
          "model": {"type": "string"},
          "licenseref": {"$ref": "#/components/schemas/LicenseRefMode"},
          "follow_external_references": {"$ref": "#/components/schemas/FollowExternalReferences"},
          "concept_keys": {"$ref": "#/components/schemas/ConceptKeys"},
          "window_cache": {"$ref": "#/components/schemas/WindowCache"},
          "tagger": {"$ref": "#/components/schemas/Tagger"},
          "license_categories": {"$ref": "#/components/schemas/LicenseCategories"},
          "licenses": {"type": "array", "items": {"$ref": "#/components/schemas/License"}},
          "exceptions": {"type": "array", "items": {"type": "string"}},
          "exception_licenses": {"type": "array", "items": {"$ref": "#/components/schemas/ExceptionLicense"}, "description": "The licenses the file's stated exceptions modify, as their own words name them (FileResult.exception_licenses)."},
          "expression": {"type": "string", "description": "The SPDX license expression the file states, where it states one (FileResult.expression)."},
          "copyrights": {"type": "array", "items": {"$ref": "#/components/schemas/Copyright"}, "description": "With copyrights: the file's copyright statements, an empty list where it holds none; absent where copyrights were not asked."},
          "holders": {"type": "array", "items": {"$ref": "#/components/schemas/HolderSpan"}, "description": "With copyrights, in scancode mode: ScanCode's holders list."},
          "spans": {"type": "integer", "description": "How many license-bearing spans the file yielded."},
          "notes": {"type": "array", "items": {"type": "string"}, "description": "Why the answer may be less than a scan would give, e.g. a pointer that cannot be followed here."},
          "stats": {"$ref": "#/components/schemas/Stats"},
          "timings": {"$ref": "#/components/schemas/Timings"}
        }
      },
      "Report": {
        "type": "object",
        "properties": {
          "repo": {"type": "string"},
          "ref": {"type": "string"},
          "commit": {"type": "string"},
          "scanner_version": {"type": "string"},
          "model": {"type": "string"},
          "generated": {"type": "string", "format": "date-time"},
          "licenseref": {"$ref": "#/components/schemas/LicenseRefMode"},
          "follow_external_references": {"$ref": "#/components/schemas/FollowExternalReferences"},
          "concept_keys": {"$ref": "#/components/schemas/ConceptKeys"},
          "window_cache": {"$ref": "#/components/schemas/WindowCache"},
          "tagger": {"$ref": "#/components/schemas/Tagger"},
          "stats": {"$ref": "#/components/schemas/Stats"},
          "timings": {"$ref": "#/components/schemas/Timings"},
          "summary": {"type": "object", "additionalProperties": {"type": "integer"}, "description": "License id -> the number of files answering it."},
          "third_party_summary": {"type": "object", "additionalProperties": {"type": "integer"}, "description": "The same count over the third-party notices documents alone (FileResult.third_party): the licenses the project says it bundles. Absent when the tree has none."},
          "expression_summary": {"type": "object", "additionalProperties": {"type": "integer"}, "description": "SPDX expression -> the number of files stating it (FileResult.expression), where `summary` counts each id of the expression once. Absent when no file states one."},
          "copyrights": {"$ref": "#/components/schemas/Copyrights"},
          "licenses": {"$ref": "#/components/schemas/Licenses"},
          "holders_summary": {"type": "array", "items": {"$ref": "#/components/schemas/HolderSummary"}, "description": "With copyrights: every holder the tree's statements name, once, ordered by files. Absent where none was asked or found."},
          "license_categories": {"$ref": "#/components/schemas/LicenseCategories"},
          "category_summary": {"type": "object", "additionalProperties": {"type": "integer"}, "description": "With license_categories: category -> the number of files holding a license of it, a file once a category however many of its licenses have it. Absent where none was asked, or no license has one."},
          "files": {"type": "array", "items": {"$ref": "#/components/schemas/FileResult"}, "description": "Only with files=true."}
        }
      }
    }
  }
}
