Producing an initial version 0.1 of the schema

[hanopcan]

We need a place to review and discuss what a first version of the DIST schema should be. We're starting on v0.0.1 and are aiming to produce a first version which will be v0.1.0, which we feel would be rounded enough to be used IRL.

We want it to be:

• Compatible with multiple impact dimensions, although to start with it will only be carbon.
• Compatible with carbon.txt.
• Able to publish concrete numbers for different taxonomy categories, but also take in prose.
• Able to make clear what methodologies were used in producing various numbers.

[hanopcan]

Hey @cronky, Thanks for initial work to get a first version of the schema working. I've taken a relatively brief look at this today.

A few things:

1. I've changed the version in the schema files to be v0.0.1 instead of v0.1.0 Our open GWF repos do get eyes on them, and I want to avoid confusion for anyone watching along. I expect there to be some discussion and amends before the schema is at v0.1, once we get to that point we can up the version number of the schema. In the meantime we can increment as we work, eg v0.0.2, v0.0.3 etc.

2. When I looked over the example file, the main thing that struck me is the repetition around the impact dimensions (eg carbon) and categories (eg upstream etc). I imagine we could make this a little neater by doing something more like (sorry if my json snytax is a little off, doing quickly to try and communicate the jist):

"impacts": [
   { "carbon": [
      { 
          "category": "upstream" [
                 {
                 "subcategory": "employee_hardware",
                 "value": 42000,
                 "unit": "kgCO2e",
                 "methodology_name": "Manufacturer LCA data amortised over device lifespan",
                 "methodology_id": DIST-100,
                 "confidence": 85,
                 "notes": "200 laptops, 180 monitors, peripherals. 4-year refresh for laptops, 6 years for monitors.",
                 "data_sources": ["https://www.apple.com/environment/"]
           },
                 "subcategory": "software",
                 "value": 0,
                 "unit": "kgCO2e",
                 "confidence": 10,
                 "notes": "Known gap. No reliable methodology for embodied emissions of commercial software."
            } ]
        "category": "direct" [ ... ],
        "category": "indirect" [ ... ],
        "category": "downstream" [ ... ],
        } ],

   _for later of course..._
   { "water": [ ... ] }
   { "materials": [ ... ] }

What do you think?

[cronky]

Version number make sense.

Fair point on repetition I guess it's a trade off between making the schema super straightforward and flat (but with repetition) vs nested. I'm happy to go with a more nested approach like you've outlined

[cronky]

Further thoughts on the structure:

The flat format looks repetitive when you read the raw JSON. But the flat approach means every record is self-contained. A tool can filter ("give me everything where dimension equals carbon"), aggregate ("sum all upstream values"), or compare ("show me cloud_services across three organisations") with simple array operations. Each record carries all the context needed to interpret it.

The nested approach is more readable when looking at the JSON, but it creates problems. Querying requires tree traversal instead of array filtering. Reporting at different levels of granularity becomes awkward: where does a dimension-level-only figure sit in a tree that expects dimension → category → subcategory? You'd need special handling. Validation gets more complex. And any tool consuming the data has to understand the nesting hierarchy rather than just iterating an array.

That said I am not a JSON specialist so I am happy to be overruled here!