Querying a SDTF graph

Learn more about how to query your SDTF token graph.

Introduction

Your token system can be more complex than it seems. You will often need to interact with your token graph to transform a specific set of design tokens within a Specify configuration.

This article will help you understand how you can query your token graph to select a specific set of tokens.

Compatible parsers

• filter

• change-case

• convert-color

• convert-dimension

Query structure

Every Query holds a single a where property being an object, to select one branch of the graph, or an array of objects, to select many branches of the graph (OR statement).

Type Query = { where: Where | Array<Where> }

The where property splits in 3 kinds: token, group, collection - offering a dedicated set of options to match against the given kind.

The name property accepts a RegExp for a value. These resources will help you debug your regular expressions:

• https://regex101.com/

• https://regexr.com/

Where Token

type WhereToken = {
  token: 
    | string
    | {
      name?: string;
      description?: string?;
    }
  select: 
    | true
    | {
      token?: boolean;
      parents?:
        | true
        | {
          groups?: true;
          collections?: true;
        }
    }
}

Where Group

type WhereGroup = {
  group: string;
  select: 
    | true
    | {
      group?: boolean;
      parents?:
        | true
        | {
          groups?: true;
          collections?: true;
        }
      children:
        | true
        | {
          groups?: true;
          collections?: true;
          tokens?: true;
        }
    }
}

Where Collection

type WhereCollection = {
  collection: string;
  select: 
    | true
    | {
      collection?: boolean;
      parents?:
        | true
        | {
          groups?: true;
        }
      children:
        | true
        | {
          groups?: true;
          tokens?: true;
        }
    }
}

Use cases

Select tokens from a specific collection

Input

{
  "primitive": {
    "$description": "`primitive` is a group used for semantic grouping.",
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      }
    }
  },
  "Colors": {
    "$description": "`Colors` is a collection.",
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    },
    "white": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from collection named 'Colors'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "collection": "^Colors$",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Output

{
  "Colors": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    },
    "white": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  }
}

Select tokens from several collections matching a naming pattern

Input

{
  "primitive": {
    "$description": "`primitive` is a group used for semantic grouping.",
    "spacing": {
      "1": {
        "$type": "dimension",
        "$description": "`primitive.spacing.1` is a dimension token without modes.",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      }
    }
  },
  "Core - Colors": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    },
    "white": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  },
  "Core - Spacing": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "space-1": {
      "$type": "spacing",
      "$value": {
        "default": { "value": 1, "unit": "px" }
      }
    },
    "space-2": {
      "$type": "spacing",
      "$value": {
        "default": { "value": 2, "unit": "px" }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from all collections whose names contain 'Core'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "where": {
              "collection": "Core",
              "select": {
                "collection": true,
                "children": {
                  "tokens": true
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Output

{
  "Core - Colors": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    },
    "white": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  },
  "Core - Spacing": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "space-1": {
      "$type": "spacing",
      "$value": {
        "default": {
          "value": 1,
          "unit": "px"
        }
      }
    },
    "space-2": {
      "$type": "spacing",
      "$value": {
        "default": {
          "value": 2,
          "unit": "px"
        }
      }
    }
  }
}

Select tokens from a specific group

Input

{
  "primitive": {
    "$description": "`primitive` is a group used for semantic grouping.",
    "spacing": {
      "1": {
        "$type": "dimension",
        "$description": "`primitive.spacing.1` is a dimension token without modes.",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      }
    },
    "font": {
      "interBold": {
        "$type": "font",
        "$value": {
          "default": {
            "family": "Inter",
            "postScriptName": "Inter Bold",
            "weight": "bold",
            "style": "normal",
            "files": [
              {
                "format": "ttf",
                "url": "https://static.specifyapp.com/sdtf-seeds/inter-bold.ttf",
                "provider": "Specify"
              }
            ]
          }
        }
      }
    }
  },
  "Text Styles": {
    "heading": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "$alias": "primitive.font.interBold",
            "$mode": "default"
          },
          "color": null,
          "fontSize": {
            "value": 32,
            "unit": "px"
          },
          "lineHeight": {
            "value": 40,
            "unit": "px"
          },
          "fontFeatures": null,
          "letterSpacing": null,
          "paragraphSpacing": null,
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": null,
          "textIndent": null,
          "textTransform": null
        }
      }
    },
    "display": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "$alias": "primitive.font.interBold",
            "$mode": "default"
          },
          "color": null,
          "fontSize": {
            "value": 56,
            "unit": "px"
          },
          "lineHeight": {
            "value": 64,
            "unit": "px"
          },
          "fontFeatures": null,
          "letterSpacing": {
            "value": -1,
            "unit": "px"
          },
          "paragraphSpacing": null,
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": null,
          "textIndent": null,
          "textTransform": null
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from the group named 'Text Styles'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "group": "^Text Styles$",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Output

{
  "Text Styles": {
    "display": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "fontSize": {
            "value": 56,
            "unit": "px"
          },
          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 64,
            "unit": "px"
          },
          "letterSpacing": {
            "value": -1,
            "unit": "px"
          },
          "paragraphSpacing": null,
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": null,
          "textIndent": null,
          "textTransform": null,
          "font": {
            "$alias": "primitive.font.interBold",
            "$mode": "default"
          }
        }
      }
    },
    "heading": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "fontSize": {
            "value": 32,
            "unit": "px"
          },
          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 40,
            "unit": "px"
          },
          "letterSpacing": null,
          "paragraphSpacing": null,
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": null,
          "textIndent": null,
          "textTransform": null,
          "font": {
            "$alias": "primitive.font.interBold",
            "$mode": "default"
          }
        }
      }
    }
  }
}

Select tokens of a specific type from a collection

Input

{
  "Android": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    },
    "white": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  },
  "primitive": {
    "gray": {
      "0": {
        "$type": "color",
        "$value": {
          "default": {
            "model": "hex",
            "hex": "#f8f9fa",
            "alpha": 1
          }
        }
      },
      "9": {
        "$type": "color",
        "$value": {
          "default": {
            "model": "hex",
            "hex": "#212529",
            "alpha": 1
          }
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get color tokens from the 'Android' collection",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "collection": "^Android$",
                "andWhere": {
                  "token": ".*",
                  "withTypes": { "include": ["color"] },
                  "select": {
                    "token": true,
                    "parents": {
                      "collections": true
                    }
                  }
                }
              }            
            }
          }
        }
      ]
    }
  ]
}

Output

{
  "Android": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    },
    "white": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  }
}

Select all tokens from a collection and from groups matching a naming pattern

Input

{
  "Android": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "primitive": {
      "gray": {
        "$type": "color",
        "$value": {
          "default": {
            "model": "hex",
            "hex": "#f8f9fa",
            "alpha": 1
          }
        }
      }
    },
    "components": {
      "black": {
        "$type": "color",
        "$value": {
          "default": {
            "model": "hex",
            "hex": "#000000",
            "alpha": 1
          }
        }
      },
      "white": {
        "$type": "color",
        "$value": {
          "default": {
            "model": "hex",
            "hex": "#FFFFFF",
            "alpha": 1
          }
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get color tokens from the 'Android' collection and from all groups named 'components'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "collection": "^Android$",
                "andWhere": {
                  "group": "^components$",
                  "andWhere": {
                    "token": ".*",
                    "withTypes": {
                      "include": ["color"]
                    },
                    "select": {
                      "token": true,
                      "parents": true
                    }
                  }
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Output

{
  "Android": {
    "$collection": {
      "$modes": [
        "default"
      ]
    },
    "components": {
      "black": {
        "$type": "color",
        "$value": {
          "default": {
            "model": "hex",
            "hex": "#000000",
            "alpha": 1
          }
        }
      },
      "white": {
        "$type": "color",
        "$value": {
          "default": {
            "model": "hex",
            "hex": "#FFFFFF",
            "alpha": 1
          }
        }
      }
    }
  }
}

Select tokens from several groups with different names

Input

{
  "group1": {
    "token1": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    }
  },
  "group2": {
    "token2": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  },
  "group3": {
    "token3": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get tokens from the group named 'Components' and/or from the group named 'Semantic'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "group": "^group1$|^group2$",
                "andWhere": {
                  "token": ".*",
                  "select": {
                    "token": true,
                    "parents": true
                  }
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Output

{
  "group1": {
    "token1": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    }
  },
  "group2": {
    "token2": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#FFFFFF",
          "alpha": 1
        }
      }
    }
  }
}

Select design tokens from a specific type

Input

{
  "dimensions": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      }
    }
  },
  "colors": {
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Get color tokens from the 'Android' collection and from all groups named 'components'",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "token": ".*",
                "withTypes": {
                  "include": [
                    "color"
                  ]
                },
                "select": {
                  "parents": true
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Output

{
  "colors": {
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    }
  }
}