ambiguity around nested vs. flat structure

A file MAY contain many tokens and they MAY be nested arbitrarily in groups like so:

{
  "token uno": {
    "$value": "#111111",
    "$type": "color"
  },
  "token group": {
    "token dos": {
      "$value": "2rem",
      "$type": "dimension"
    },
    "nested token group": {
      "token tres": {
        "$value": 33,
        "$type": "number"
      },
      "Token cuatro": {
        "$value": 444,
        "$type": "fontWeight"
      }
    }
  }
}

But 6.2.1 also states:

Groups let token file authors better organize their token files. Related tokens can be nested into groups to align with the team's naming conventions and/or mental model. When manually authoring files, using groups is also less verbose than a flat list of tokens with repeating prefixes.
"brand": {
"color": {
"$type": "color",
"acid green": {
"$value": "#00ff66"
}
},

...is likely to be more convenient to type and, arguably, easier to read, than:

  "brand-color-acid-green": {
    "$value": "#00ff66",
    "$type": "color"
  },

Does that mean the two are supposed to represent the same thing? Because the first example represents a token "acid green" and the second example represents a different token "brand-color-acid-green".

This seems to suggest there are two different ways to parse a token file: nested or flat. Nested means I should consider the entire token path as part of the token name. Flat means I should assume that the token name is already flat and that any nested paths are just an arbitrary way of grouping items.

It's very confusing to see that:

    "nested token group": {
      "token tres": {
        "$value": 33,
        "$type": "number"
      }

represents a token named token-tres and NOT nested-token-group-token-tres while also seeing that

  "brand": {
    "color": {
      "$type": "color",
      "acid green": {
        "$value": "#00ff66"
      }
    },

represents a token named brand-color-acid-green.

I feel like it should be possible to consume a .token file and be able to output a list of all the available design tokens using only the format. Would it be possible to add more clarification around these concepts?

I guess your issue is more toward the practices rather the format. The parts you are referring to are non-normative in the sense they present the possibility and leave users choose for themselves.

Does that mean the two are supposed to represent the same thing?

Those two token trees are different, yet one team may prefer one approach while others prefer the other. To avoid vocabulary confusion, I personally use "path" for the path of the token within the tree, and "name" for the actual token name — the name is also the last element of the path.

I feel like it should be possible to consume a .token file and be able to output a list of all the available design tokens using only the format.

If the choice is to use only flat tokens, it's pretty straightforward. Whenever there're groups, you need some kind of object traversal function to figure out the tokens list. I making a lib doing that btw.

design-tokens / community-group

ambiguity around nested vs. flat structure #253