md`Do cubes and lists suffice? Statistical datasets are usually big. For performance reasons, statistical offices won’t allow to retrieve a full cube if it has many cells. Besides, consumers are usually interested in just a certain aspect (a side) of the cube. Fetching/serving full datasets is generally not efficient for anybody (consumer or provider): a way to filter the data inside the cube is required. But before filtering a dataset, a consumer needs to know how it can be filtered: to this end, the API must be able to expose the dataset *before* exposing its data. In summary, it needs to provide a way to share dataset metadata. Let’s take Statistics Denmark’s API as an example of an statistical API that covers all the stages. Denmark’s query builder (“API Console” as they call it) supports four types of API calls:

${await FileAttachment("denmark-calls.png").image()}

https://api.statbank.dk/console

As you can see in the pull-down menu, Denmark’s API accepts the following requests: 1. (list of) subjects 2. (list of) tables 3. metadata for a table 4. data (for a table) Four types of calls, four response schemas, four formats. JSON-stat (v.1) is used in the last type of call, but Denmark could use JSON-stat v.2 for calls 1 (collections of subjects), 2 (collection of datasets) and 4 (datasets). What about the third type? What’s the JSON-stat schema to expose specifically dataset metadata? The answer is “None”. Because none is needed. Specifically. A very important design principle of JSON-stat is the strict separation between a cube’s data and a cube’s metadata. As a consequence data can be cleanly removed from JSON-stat datasets: these can be used to expose data but also to describe a cube’s metadata. The exact same schema serves both ends. Where Denmark uses four different formats, a fully JSON-stat-based API would only require two (collections and datasets). If a statistical office API (like Eurostat’s) disseminates datasets using JSON-stat, it can disseminate dataset metadata for (nearly) free. If it can build a full dataset, it can build an empty one because: In JSON-stat, an empty dataset is exactly the same as a full dataset minus the property “status” (which is optional and contains metadata at the cell level) and “value” (which contains the actual data). “value” is required but can be empty. The JSON-stat Dataset Schema allows "value": {} or "value": [] (The [jsonstat-toolkit](https://www.npmjs.com/package/jsonstat-toolkit) is even more tolerant and will accept "value": null or even no value property at all, but that’s beyond the current specification.) `