[BUG] Fragmented Tokens (a la Collections)

[CITguy]

Fragmented Definition

If tokens are meant to be the source of truth, then defining tokens directly in a collection introduces fragmentation by allowing multiple places for tokens to be defined.

If I were to fetch a list of all tokens in a DSP, not only do I have to look for Token entities ({ type: 'token' }; which makes sense), but I also have to be aware of tokens defined in Collection entities ({ type: 'collection', tokens: [ ... ] }).

1. What happens if I define a token alias inside of a Collection?
   • Does the token alias another collection token?
   • Does it alias a Token entity (external to collection)?
   • Does it alias a Token defined in a different Collection?
2. What happens if I define a Collection token with the same id as a Token entity?

Fragmented Data Structure

In addition to above, it's also unclear how a DSP consumer should normalize the definition of a token, because a Token entity and a Collection token have different data structures.

Property	Token entity	Collection token
class	x	implied
type	x	x
id	x	x
name	x
value	x	x
last_updated	x
last_update_author	x
description	x
key		x

• How does the key property differ from id in a Collection token?
• How do I know when a specific Collection token was last updated?
  • You can tell when the Collection was last updated, but not individual tokens within it.
• How do I know who last updated a Collection token?
  • You can tell who last updated the Collection, but not individual tokens within it.

Proposed Solution

What if we were to update Collection entities to act as a logical grouping of Token references, instead of a physical grouping of Token values?

• Token entities would serve as the single source of truth for Token definition
• Collections then reference Token entities via an "entity_refs" property
  • NOTE: data structure needs clarification (see "Unanswered Questions" below)

example:

{
    "dsp_spec_version": "1.0",
    "last_updated": "UTCDateTime",
    "last_updated_by": "Author Name",
    "entities": [
        {
            "class": "collection",
            "type": "custom",
            "id": "my-first-collection",
            "last_updated": "UTCDateTime",
            "last_updated_by": "Author Name",
            "description": "First Collection Description",
            "tags": [
                "tag1",
                "tag2",
                "tag3"
            ],
            "entity_refs": [
                "{entity-id-1}",
                "{entity-id-2}",
                "{entity-id-3}"
            ],
        },
        {
            "class": "collection",
            "type": "custom",
            "id": "my-second-collection",
            "last_updated": "UTCDateTime",
            "last_updated_by": "Author Name",
            "description": "Second Collection Description",
            "tags": [
                "tag3"
            ],
            "entity_refs": [
                "{entity-id-7}",
                "{entity-id-8}",
                "{entity-id-42}"
            ]
        }
    ]
}

Unanswered Questions

• What does the data format look like for "entity_refs"?
  • array of "{Entity-ID}" strings
  • array of "Entity-ID" strings
  • something else?
• Does "entity_refs" need to be ordered?
  • Could we use an { "<alias>": "<token-entity-id>" } object format?