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
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:
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
{
"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
}
}
}
}
}.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
}
}
}
}
}
]
}
]
}{
"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
{
"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" }
}
}
}
}.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
}
}
}
}
}
]
}
]
}{
"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
{
"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
}
}
}
}
}.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
}
}
}
}
}
]
}
]
}{
"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
{
"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
}
}
}
}
}
}.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
}
}
}
}
}
}
}
]
}
]
}{
"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
{
"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
}
}
}
}
}
}.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
}
}
}
}
}
}
}
]
}
]
}{
"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
{
"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
}
}
}
}
}.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
}
}
}
}
}
}
]
}
]
}{
"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
{
"dimensions": {
"spacing": {
"1": {
"$type": "dimension",
"$value": {
"default": {
"value": 4,
"unit": "px"
}
}
}
}
},
"colors": {
"black": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
}
}
}.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
}
}
}
}
}
]
}
]
}{
"colors": {
"black": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
}
}
}Last updated