{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://patte-blanche.org/claims.schema.json",
  "title": "claims.json",
  "description": "Every figure the pages of How France works show, each with its definition, its source and the arithmetic between the source and the page, under claims, after the release they belong to. tables/bands_claims.json follows the same schema.",
  "type": "object",
  "required": [
    "name",
    "version",
    "commit",
    "date",
    "licence",
    "licence_url",
    "third_party",
    "claims"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "The site's name."
    },
    "version": {
      "type": "string",
      "description": "The release: a tag YYYY.MM, git describe's YYYY.MM-N-gHASH after one, or unreleased-HASH."
    },
    "commit": {
      "type": "string",
      "description": "The commit the figures are built from."
    },
    "date": {
      "type": "string",
      "description": "That commit's date, YYYY-MM-DD."
    },
    "licence": {
      "type": "string",
      "description": "The licence of the text and the figures."
    },
    "licence_url": {
      "type": "string",
      "description": "Where the licence is published."
    },
    "third_party": {
      "type": "string",
      "description": "The terms of third-party data."
    },
    "citation": {
      "type": "string",
      "description": "How to cite a figure, its id for <id>."
    },
    "permalink": {
      "type": "string",
      "description": "The URL of a figure's permanent page, from its id."
    },
    "claims": {
      "type": "array",
      "description": "The figures.",
      "items": {
        "$ref": "#/$defs/claim"
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "claim": {
      "type": "object",
      "description": "One figure the pages show, with its provenance.",
      "required": [
        "id",
        "label",
        "value",
        "unit",
        "year",
        "status",
        "definition",
        "origin",
        "retrieved"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "The claim's identifier, unique in the file."
        },
        "label": {
          "type": "string",
          "description": "What the figure is, in a few words."
        },
        "value": {
          "type": "number",
          "description": "The value, in unit."
        },
        "unit": {
          "enum": [
            "EUR million",
            "EUR billion",
            "percent",
            "percent of GDP",
            "percentage points",
            "count",
            "EUR",
            "USD billion",
            "ratio"
          ],
          "description": "The value's unit."
        },
        "year": {
          "type": "integer",
          "description": "The year the figure refers to."
        },
        "status": {
          "enum": [
            "observed",
            "estimated",
            "hypothetical"
          ],
          "description": "Observed: a published accounting or administrative figure; estimated: a model, an imputation or a survey; hypothetical: a scenario."
        },
        "definition": {
          "type": "string",
          "description": "What the figure counts."
        },
        "origin": {
          "description": "Where the figure comes from.",
          "oneOf": [
            {
              "$ref": "#/$defs/eurostat"
            },
            {
              "$ref": "#/$defs/document"
            },
            {
              "$ref": "#/$defs/assumption"
            },
            {
              "$ref": "#/$defs/derived"
            }
          ]
        },
        "retrieved": {
          "type": "string",
          "description": "When the source was read, YYYY-MM-DD, or empty."
        },
        "caveat": {
          "type": "string",
          "description": "What a reader should know before using the figure."
        },
        "kind": {
          "enum": [
            "stock",
            "flow"
          ],
          "description": "Stock: an amount held at a date, such as wealth or debt; flow: an amount over a period, such as income, a levy or a transfer. Absent for a figure that is neither, or not yet classified."
        },
        "alternatives": {
          "type": "array",
          "description": "Competing figures and why they differ.",
          "items": {
            "$ref": "#/$defs/alternative"
          }
        }
      },
      "additionalProperties": false
    },
    "eurostat": {
      "type": "object",
      "description": "A cell of a Eurostat dataset.",
      "required": [
        "kind",
        "dataset",
        "filters",
        "time",
        "updated",
        "provisional",
        "url"
      ],
      "properties": {
        "kind": {
          "const": "eurostat"
        },
        "dataset": {
          "type": "string",
          "description": "The dataset code, such as gov_10a_main."
        },
        "filters": {
          "type": "object",
          "description": "Dimension and code pairs selecting one cell, the time excepted.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "time": {
          "type": "integer",
          "description": "The year of the cell."
        },
        "updated": {
          "type": "string",
          "description": "The dataset's update stamp when it was read."
        },
        "provisional": {
          "type": "boolean",
          "description": "Whether Eurostat flags the cell provisional."
        },
        "url": {
          "type": "string",
          "description": "The API query returning exactly this cell."
        }
      },
      "additionalProperties": false
    },
    "document": {
      "type": "object",
      "description": "A figure read from a publication.",
      "required": [
        "kind",
        "publisher",
        "title",
        "url",
        "location",
        "published"
      ],
      "properties": {
        "kind": {
          "const": "document"
        },
        "publisher": {
          "type": "string",
          "description": "Who published it."
        },
        "title": {
          "type": "string",
          "description": "The publication's title."
        },
        "url": {
          "type": "string",
          "description": "Where it is published."
        },
        "location": {
          "type": "string",
          "description": "The page, table or cell holding the figure."
        },
        "published": {
          "type": "string",
          "description": "When it was published, as the publisher dates it."
        },
        "quote": {
          "type": "string",
          "description": "The sentence or row the figure is read from."
        }
      },
      "additionalProperties": false
    },
    "assumption": {
      "type": "object",
      "description": "A scenario parameter, not read from any source.",
      "required": [
        "kind",
        "rationale"
      ],
      "properties": {
        "kind": {
          "const": "assumption"
        },
        "rationale": {
          "type": "string",
          "description": "Why it was chosen."
        }
      },
      "additionalProperties": false
    },
    "derived": {
      "type": "object",
      "description": "A figure computed from other claims.",
      "required": [
        "kind",
        "formula",
        "inputs"
      ],
      "properties": {
        "kind": {
          "const": "derived"
        },
        "formula": {
          "type": "string",
          "description": "The computation, over the inputs' labels."
        },
        "inputs": {
          "type": "array",
          "description": "The ids of the claims it is computed from.",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "alternative": {
      "type": "object",
      "description": "A competing figure for the same quantity.",
      "required": [
        "value",
        "source",
        "why"
      ],
      "properties": {
        "value": {
          "type": "string",
          "description": "The competing figure, as its source states it."
        },
        "source": {
          "type": "string",
          "description": "Who states it."
        },
        "why": {
          "type": "string",
          "description": "Why it differs from the claim."
        },
        "url": {
          "type": "string",
          "description": "Where it is stated."
        }
      },
      "additionalProperties": false
    }
  }
}
