◇ Open Values Standardfor builders

Spec / open-values-category-index

Open Values Category Index v0.2

The list of every live category on Conscious Consuming, such as coffee or banking, with its criteria, the human need it serves, and where its data file is, plus the full category tree and the data credit line. The dataset build (pipeline/build_datasets.py) writes it to app/data/index.json, and the app reads it first to draw the browse tree and find each category's file.

Stable. A change that breaks existing files needs a new version. A file a build step makes from other files. Change the sources, not this file.

Who writes it and who reads it

Written by pipeline/build_datasets.py. Read by Round 11 needs map, app browse tree, Ask, Round 4 decision-page contract loader, public routes.

Fields

FieldWhat it meansType
categories requiredOne summary per live category: its name, file, size, criteria, need and place in the site navigation.list
attribution requiredThe credit line for data the categories reuse, such as "Data © Open Food Facts contributors (ODbL)".string
ontology requiredThe full category tree, copied from content/ontology.json: the eight needs, the domains and the categories under them.a ontology-v0.4 file
regionDecisionContractHow the app filters entries by region, which categories have a region filter, and which entries the current region values cannot place correctly.see regionDecisionContract
namingContractThe rules for when to use each of the three project names (Values Commons, Open Values Standard, Conscious Consuming), and which parts of the app should follow them.see namingContract

A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.

A file that passes

Category indexes list built category files and embed the ontology.

{
  "categories": [
    {
      "id": "tea",
      "label": "Tea",
      "file": "tea.json",
      "n": 120,
      "type": "Products",
      "criteria": [
        {
          "key": "environment",
          "label": "Environment"
        }
      ],
      "need": "nourish",
      "domain": "Food"
    }
  ],
  "attribution": "Fixture attribution",
  "ontology": {
    "version": 4,
    "types": [
      "Products"
    ],
    "needs": [
      {
        "id": "nourish",
        "label": "NOURISH",
        "reads": "Food and drink."
      },
      {
        "id": "care",
        "label": "CARE",
        "reads": "Bodies and wellbeing."
      },
      {
        "id": "keep-a-home",
        "label": "KEEP A HOME",
        "reads": "A working home."
      },
      {
        "id": "connect",
        "label": "CONNECT",
        "reads": "People and services."
      },
      {
        "id": "move",
        "label": "MOVE",
        "reads": "Journeys and transport."
      },
      {
        "id": "learn",
        "label": "LEARN",
        "reads": "Knowledge and media."
      },
      {
        "id": "give-and-act",
        "label": "GIVE & ACT",
        "reads": "Causes and action."
      },
      {
        "id": "protect",
        "label": "PROTECT",
        "reads": "Money and security."
      }
    ],
    "domains": [
      {
        "label": "Food",
        "categories": [
          {
            "label": "Tea",
            "cid": "tea",
            "type": "Products",
            "need": "nourish"
          }
        ]
      }
    ]
  }
}

A file that must be rejected

Category summaries must name their generated JSON file.

{
  "categories": [
    {
      "id": "tea",
      "label": "Tea",
      "n": 120,
      "type": "Products",
      "criteria": [
        {
          "key": "environment",
          "label": "Environment"
        }
      ],
      "domain": "Food"
    }
  ],
  "attribution": "Fixture attribution",
  "ontology": {
    "version": 3,
    "types": [
      "Products"
    ],
    "domains": []
  }
}

The schema

Its address is https://openvaluesstandard.org/schema/category-index-v0.2.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/category-index.schema.json.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.