{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artwaste.land/coins/api/schema.json",
  "title": "Australian coin catalogue",
  "description": "A catalogue in which every number carries the document it came from, the basis on which it was counted, and the words that were actually printed. Where sources disagree the catalogue keeps both figures rather than picking one.",
  "type": "object",
  "required": [
    "version",
    "generated",
    "sources",
    "types",
    "issues",
    "facts"
  ],
  "properties": {
    "version": {
      "type": "string"
    },
    "generated": {
      "type": "string",
      "format": "date"
    },
    "licence": {
      "type": "string"
    },
    "sources": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/source"
      }
    },
    "types": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/type"
      }
    },
    "issues": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/issue"
      }
    },
    "varieties": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/variety"
      }
    },
    "facts": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/fact"
      }
    },
    "production": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/production"
      }
    }
  },
  "$defs": {
    "source": {
      "type": "object",
      "description": "A citable document. Nothing enters the catalogue without one.",
      "required": [
        "id",
        "title",
        "url",
        "tier",
        "accessed"
      ],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^src:[a-z0-9-]+$"
        },
        "title": {
          "type": "string"
        },
        "publisher": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "http_status": {
          "type": "integer"
        },
        "accessed": {
          "type": "string",
          "format": "date"
        },
        "published": {
          "type": "string"
        },
        "tier": {
          "type": "string",
          "description": "How close to the striking of the coin this document sits.",
          "enum": [
            "statute",
            "mint",
            "archive",
            "museum",
            "scholarly",
            "trade",
            "hobbyist"
          ]
        },
        "licence": {
          "type": "string",
          "description": "The licence or terms actually stated by the publisher, or UNKNOWN. Never guessed."
        },
        "reuse": {
          "type": "string",
          "description": "What we may do with it, decided once and recorded.",
          "enum": [
            "quote-and-cite",
            "cite-only",
            "reproduce-freely"
          ]
        }
      }
    },
    "type": {
      "type": "object",
      "description": "A design and specification period for one denomination.",
      "required": [
        "id",
        "denomination",
        "from",
        "specification"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^type:[a-z0-9-]+$"
        },
        "denomination": {
          "type": "string"
        },
        "series": {
          "type": "string",
          "enum": [
            "pre-decimal",
            "decimal",
            "gold",
            "colonial"
          ]
        },
        "from": {
          "type": "integer"
        },
        "to": {
          "type": [
            "integer",
            "null"
          ]
        },
        "obverse": {
          "type": "object",
          "properties": {
            "monarch": {
              "type": "string"
            },
            "portrait": {
              "type": "string"
            },
            "designer": {
              "type": "string"
            },
            "legend": {
              "type": "string",
              "description": "Transcribed from the coin, verbatim."
            }
          }
        },
        "reverse": {
          "type": "object",
          "properties": {
            "design": {
              "type": "string"
            },
            "designer": {
              "type": "string"
            },
            "legend": {
              "type": "string"
            }
          }
        },
        "specification": {
          "$ref": "#/$defs/specification"
        }
      }
    },
    "specification": {
      "type": "object",
      "description": "Physical standard. Statutory values are quoted in the units the instrument printed; any conversion is recorded as a separate derived field so the original is never lost.",
      "properties": {
        "instrument": {
          "type": "string",
          "description": "Source id of the Act, regulation or proclamation that sets it."
        },
        "in_force_from": {
          "type": "string"
        },
        "in_force_to": {
          "type": [
            "string",
            "null"
          ]
        },
        "standard_weight": {
          "type": "object",
          "properties": {
            "as_printed": {
              "type": "string",
              "description": "Exactly as the instrument prints it, e.g. '145.83333 grains / 9.44984 g'."
            },
            "grams": {
              "type": [
                "number",
                "null"
              ]
            },
            "grains": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        },
        "composition": {
          "type": "object",
          "properties": {
            "as_printed": {
              "type": "string",
              "description": "The instrument's own words, e.g. 'One-half fine silver, one-half alloy; or millesimal fineness 500'."
            },
            "fine_metal": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "silver",
                "gold",
                null
              ]
            },
            "fineness_millesimal": {
              "type": [
                "number",
                "null"
              ]
            },
            "alloy_breakdown": {
              "type": [
                "object",
                "null"
              ],
              "description": "Only populated where an instrument states it. The widely repeated 40% copper / 5% zinc / 5% nickel breakdown of the post-1947 alloy is NOT in the Act and must not be recorded here as statutory."
            },
            "alloy_breakdown_basis": {
              "type": "string",
              "enum": [
                "statutory",
                "mint-stated",
                "secondary",
                "unsourced"
              ]
            }
          }
        },
        "fine_metal_weight": {
          "type": "object",
          "description": "Derived, not quoted. This is what a melt calculation uses, so its derivation is shown.",
          "properties": {
            "grams": {
              "type": [
                "number",
                "null"
              ]
            },
            "troy_ounces": {
              "type": [
                "number",
                "null"
              ]
            },
            "derivation": {
              "type": "string",
              "description": "The arithmetic, in words, from the two quoted statutory figures."
            }
          }
        },
        "diameter_mm": {
          "type": [
            "number",
            "null"
          ]
        },
        "thickness_mm": {
          "type": [
            "number",
            "null"
          ]
        },
        "shape": {
          "type": "string"
        },
        "edge": {
          "type": "string"
        },
        "remedy": {
          "type": "string",
          "description": "The legal tolerance, as printed."
        }
      }
    },
    "issue": {
      "type": "object",
      "description": "A dated striking: a type, a year borne by the coin, and where known a mint.",
      "required": [
        "id",
        "type",
        "year"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^au-[a-z0-9-]+$"
        },
        "type": {
          "type": "string"
        },
        "year": {
          "type": "integer"
        },
        "mint": {
          "type": [
            "string",
            "null"
          ]
        },
        "mintmark": {
          "type": [
            "string",
            "null"
          ],
          "description": "The mark physically on the coin. Distinct from `mint`, which is a sourced claim about where it was struck. Where the literature disagrees about the second, the first is still observable."
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "commemorative": {
          "type": [
            "string",
            "null"
          ]
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "variety": {
      "type": "object",
      "required": [
        "id",
        "issue",
        "name",
        "evidence"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "issue": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "identified_by": {
          "type": "string",
          "description": "What a person physically looks at to tell it apart."
        },
        "evidence": {
          "type": "string",
          "description": "How well attested it is. `folklore` is a real and useful answer: it means widely repeated with no traceable source, and the catalogue says so out loud.",
          "enum": [
            "primary",
            "scholarly",
            "trade",
            "hobbyist",
            "folklore"
          ]
        },
        "sources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "fact": {
      "type": "object",
      "description": "The atomic unit of the catalogue. One property of one subject, with every value anyone has published for it.",
      "required": [
        "subject",
        "field",
        "values"
      ],
      "properties": {
        "subject": {
          "type": "string",
          "description": "An issue, type or variety id."
        },
        "field": {
          "type": "string",
          "examples": [
            "mintage",
            "surviving_population",
            "diameter_mm"
          ]
        },
        "values": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "value",
              "source",
              "basis"
            ],
            "properties": {
              "value": {
                "type": [
                  "number",
                  "string",
                  "null"
                ]
              },
              "unit": {
                "type": "string"
              },
              "basis": {
                "type": "string",
                "description": "WHAT WAS COUNTED. The commonest error in published coin data is treating these as the same number. They are not.",
                "enum": [
                  "struck-dated",
                  "struck-in-report-year",
                  "delivered",
                  "issued",
                  "final-mintage-as-published",
                  "surviving-graded-population",
                  "unstated"
                ]
              },
              "rounded": {
                "type": "boolean",
                "description": "True where the source publishes to millions or similar, e.g. RAM's web tables."
              },
              "source": {
                "type": "string"
              },
              "locator": {
                "type": "string",
                "description": "Page, table or appendix within the source."
              },
              "url": {
                "type": "string"
              },
              "quote": {
                "type": "string",
                "description": "The source's own words containing the figure. Verbatim, including OCR artefacts, which are flagged rather than corrected."
              },
              "quote_is_ocr": {
                "type": "boolean"
              },
              "accessed": {
                "type": "string",
                "format": "date"
              },
              "mint": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The striking mint this figure is attributed to, as the source names it. Codes are kept as printed and expanded only where an expansion can be cited."
              },
              "component": {
                "type": "boolean",
                "description": "True when this figure is one PART of a year's production rather than a rival claim about the whole. RAM splits 1981 one cent across two mints; those are components summing to a total, not two people disagreeing. Conflating the two is how a catalogue invents a contradiction that is not there."
              },
              "precision": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Half the last printed place, in pieces. A figure printed as 133.3 million is exact to +/- 50,000 and the catalogue says so rather than implying nine significant figures."
              },
              "marker": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A footnote marker printed against the figure in the source, kept even when the source defines no legend for it."
              },
              "quote_kind": {
                "type": "string",
                "enum": [
                  "verbatim-span",
                  "reconstructed-row",
                  "flattened-table-row"
                ],
                "description": "verbatim-span: a contiguous run of characters copied from the source, which the verifier re-finds in the cached document. reconstructed-row: a table row rendered as text, whose individual cells the verifier re-finds. Anything a verifier cannot re-find in the source does not ship."
              },
              "source_cache": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Path to the cached copy of the source the quote was taken from, so the claim can be re-checked offline."
              },
              "reading": {
                "type": "string",
                "enum": [
                  "checksum-confirmed",
                  "positional-only"
                ],
                "description": "For figures read from a table the transcription service flattens. A flattened table divorces a number from its row label, so a positional reading can be confidently wrong and a quote check cannot catch it. checksum-confirmed means the table carried its own arithmetic control and it closed."
              }
            }
          }
        },
        "resolution": {
          "type": "object",
          "description": "What the catalogue says when asked for one number. It is allowed to answer that it does not know.",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "agreed",
                "disputed",
                "single-source",
                "different-basis",
                "summed-from-components",
                "unsourced",
                "report-total-below-website"
              ]
            },
            "value": {
              "type": [
                "number",
                "string",
                "null"
              ]
            },
            "note": {
              "type": "string"
            },
            "components_summed": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "production": {
      "type": "object",
      "description": "What a mint struck, delivered or issued DURING a report year. This is not an issue mintage and must never be rendered as one: the date borne by the coin is a separate fact the reports usually do not state, and a single year's delivery routinely carries two dates.",
      "required": [
        "report_year",
        "mint",
        "denomination",
        "basis",
        "source",
        "quote"
      ],
      "properties": {
        "report_year": {
          "type": "integer"
        },
        "mint": {
          "type": "string"
        },
        "denomination": {
          "type": "string"
        },
        "as_printed": {
          "type": "string",
          "description": "The figure exactly as the page prints it, OCR damage included."
        },
        "printed_unit": {
          "type": "string",
          "enum": [
            "pounds",
            "pieces",
            "unstated"
          ],
          "description": "Which the DOCUMENT printed. Australian mints kept these books in pounds sterling, so this is usually 'pounds'."
        },
        "pounds": {
          "type": [
            "number",
            "null"
          ]
        },
        "pieces": {
          "type": [
            "number",
            "null"
          ]
        },
        "coins_per_pound": {
          "type": [
            "number",
            "null"
          ],
          "description": "240 pennies, 480 halfpence, 40 sixpences, 20 shillings, 10 florins, 4 crowns, 1 sovereign."
        },
        "derived": {
          "type": [
            "object",
            "null"
          ],
          "description": "A conversion, shown rather than performed in place, so the printed figure is never overwritten by an inferred one."
        },
        "basis": {
          "type": "string",
          "enum": [
            "struck-dated",
            "struck-in-report-year",
            "delivered",
            "issued",
            "unstated"
          ]
        },
        "coin_date": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Only where the document states the date borne by the coin. Null is the common and honest answer."
        },
        "source": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "quote": {
          "type": "string"
        },
        "quote_kind": {
          "type": "string"
        }
      }
    }
  }
}