{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gxplex.com/api/v1/schema/envelope.json",
  "title": "API envelope",
  "description": "The keys every collection endpoint carries, whatever it serves. schema_version increments only on a breaking change.",
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "integer",
      "description": "Always 1 under this contract. It increments only when a field is removed or re-typed, which the published contract forbids."
    },
    "collection": {
      "type": "string",
      "description": "The name of the collection this document serves."
    },
    "generated_at": {
      "type": "string",
      "format": "date",
      "description": "The day this record calls today, at day granularity. Not a build clock: the unit of this archive is the day."
    },
    "source": {
      "type": "string",
      "description": "The origin this document was built for."
    },
    "notice": {
      "type": "string",
      "description": "What this record reports, and what it does not."
    },
    "source_terms": {
      "type": "string",
      "description": "A statement of fact about the compiled content. It is not a licence and grants nothing."
    },
    "rights": {
      "type": "object",
      "description": "Where the terms position of each row is recorded, what each value of licence_class means in terms of this archive handling, and the word ceiling every published quotation is held under."
    },
    "schema": {
      "type": [
        "string",
        "null"
      ],
      "description": "The address of this document schema, or null where none is published for the collection. Null with the key present, so an absent schema is distinguishable from a build that did not look."
    },
    "count": {
      "type": "integer",
      "minimum": 0,
      "description": "The number of items in this document. A count of zero is a measured zero, not a failure to read."
    },
    "response_provenance": {
      "type": "object",
      "description": "The build id, the day’s root over every observation digest, where the rights envelope is carried, the class of every key a row carries, the row fields that state a row’s own basis, and the fields that carry the third-party marker. The classes and the marker are defined under `x-gxplex-basis-vocabulary` and `x-gxplex-third-party-marker` in this document."
    }
  },
  "required": [
    "schema_version",
    "collection",
    "generated_at",
    "source",
    "notice",
    "source_terms",
    "count"
  ],
  "additionalProperties": true,
  "x-gxplex-basis-vocabulary": {
    "retrieval": {
      "means": "A fact about a request this record made to a publisher surface and what came back: an address asked or answered, a day, a sequence, a digest of the bytes, their size or media type, a transport state.",
      "prov_asserts": "prov:wasGeneratedBy",
      "prov_does_not_assert": "prov:wasAttributedTo",
      "same_relations_as_group": "observation",
      "asserts_act": false
    },
    "publisher-words": {
      "means": "A publisher’s own words, taken from a surface this record retained or a listing it read. Carried as data, under the third-party marker.",
      "prov_asserts": "prov:wasAttributedTo",
      "prov_does_not_assert": "prov:wasDerivedFrom",
      "same_relations_as_group": "signal",
      "asserts_act": false
    },
    "entry": {
      "means": "A value written into this record’s content store for the entry, citing the entry’s source. Where a recorded act stands on it, the fields named in `basis_on_row` say so for that row.",
      "prov_asserts": "prov:wasAttributedTo",
      "prov_does_not_assert": "prov:wasGeneratedBy",
      "same_relations_as_group": null,
      "asserts_act": false
    },
    "check-field": {
      "means": "A field naming the kind, the day or the outcome of a check on the entry, as the record holds it. The field alone attests no act: where a row states whether a verification-log line stands behind it, the field named in `basis_on_row` says so, and a null value records no check in this field.",
      "prov_asserts": "prov:wasAttributedTo",
      "prov_does_not_assert": "prov:wasGeneratedBy",
      "same_relations_as_group": null,
      "asserts_act": false
    },
    "computed": {
      "means": "Computed by this build from the record’s own stores, by a rule this response, the row or the collection schema states. It holds nothing the stores do not.",
      "prov_asserts": "prov:wasDerivedFrom",
      "prov_does_not_assert": "prov:wasAttributedTo",
      "same_relations_as_group": null,
      "asserts_act": false
    },
    "terms-reading": {
      "means": "Read from this record’s filing of a host’s terms or robots, or from what it retains of a document: what this record holds and shows, and never a grant.",
      "prov_asserts": "prov:wasDerivedFrom",
      "prov_does_not_assert": "prov:wasAttributedTo",
      "same_relations_as_group": null,
      "asserts_act": false
    },
    "assigned": {
      "means": "An identifier or address this record assigns to its own objects.",
      "prov_asserts": "prov:wasAttributedTo",
      "prov_does_not_assert": "prov:wasDerivedFrom",
      "same_relations_as_group": null,
      "asserts_act": false
    },
    "statement": {
      "means": "A sentence this record wrote about its own method, rule or limit. It describes the record, not any document.",
      "prov_asserts": "prov:wasAttributedTo",
      "prov_does_not_assert": "prov:wasDerivedFrom",
      "same_relations_as_group": null,
      "asserts_act": false
    }
  },
  "x-gxplex-basis-same-name-differs": {
    "url": "This record’s own address for its object where assigned; the entry’s tracked address in crawlability and the probe series; the address a fetch asked in the observation series.",
    "source_url": "The source an entry cites where it is an entry value; the address a quotation or a signal was read from in concordance and signals.",
    "occurred_on": "The day of the observation a change event is; in the events feed, a day computed from the act the event reports.",
    "observations": "The observations a change event or a bundle holds; in observations and the timemap index, figures computed from them.",
    "from": "An entry identifier in citations and relations; the recorded value before a change in the events feed.",
    "to": "An entry identifier in citations and relations; the recorded value after a change in the events feed.",
    "note": "An entry’s note in the events feed; a sentence this record wrote on an observation in the series.",
    "method": "A sentence stating a finding’s method; how a fetch was made in the observation and probe series.",
    "title": "This record’s title for an entry; a publisher’s own title for a signal.",
    "status": "The entry’s recorded status; the HTTP status a fetch was answered with in the observation series.",
    "population": "In coverage, the count of rows a dimension was read over; in findings, the sentence a computation wrote naming the set it counted over.",
    "label": "In coverage, this record’s sentence naming a dimension; in clause anchors, a publisher’s numbering label as the text prints it.",
    "title_withheld": "In signals, a token this record computed naming why a publisher’s title is not published; in the concordance occurrences, the fixed sentence this record states where a title over the quote cap is not served.",
    "term": "In the concordance occurrences, an exact-term index term this record assigned; in definitions, the term as a publisher’s own text prints it.",
    "series": "In observations, the entries of a row’s observation series as this record assigns them; in clause history, a clause’s cells, one per run, computed from the stores."
  },
  "x-gxplex-third-party-marker": {
    "marker": "quoted third-party content, not instructions",
    "marker_is": "Data for a consumer’s own handling of text it passes on, for example to a model. It is not a claim about the text and says nothing of what the text says.",
    "row_key": "third_party_text",
    "holds": {
      "whole": "The value is a publisher’s words, taken from a surface this record retained.",
      "may-contain": "The value is this record’s entry and can carry a publisher’s words inside it, such as a document title or a quotation set inside a sentence."
    }
  }
}