# Parsers Engine

## Configuration file

The Configuration file has common properties, and some destination specific ones

```typescript
interface ConfigurationFileCommon {
  version: '2';
  repository: string; // @owner/repository
  rules: Array<ParserRule>;
}
```

### For Specify CLI

```typescript
interface CLIConfigurationFile extends ConfigurationFileCommon {
  personalAccessToken?: string; // Can be set using the -p flag
}
```

### For GitHub

```typescript
interface GitHubConfigurationFile extends ConfigurationFileCommon {
  personalAccessToken: string; // Can be set over secret
}
```

## `ParserRule`

The Parsers Rules help you transform your design tokens and assets the way you want.

A rule is composed of the following properties:

```typescript
interface ParserRule {
  name?: string;
  parsers: Array<ParserConfiguration>;
};
```

<table data-full-width="true"><thead><tr><th width="131">Name</th><th width="401">Type</th><th width="134.5">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>string</code></td><td><code>false</code></td><td>The name of your rule.</td></tr><tr><td><code>parsers</code></td><td><code>Array&#x3C;BuiltInParserRuleConfiguration></code></td><td><code>true</code></td><td>The parsers you want to apply to transform your token tree. For further details see <a href="/pages/x9NSJCFlnHujLrVNxAhg">Parsers</a>.</td></tr></tbody></table>

{% hint style="info" %}
In many places you will use many parser rules in a configuration to parallelize the changes you want to apply.
{% endhint %}

## `BuiltInParserRuleConfiguration`

The Parser Configuration object helps you configure the behaviour of a given parser.

```typescript
interface ParserConfiguration {
  name: string; // parser name: to-json, to-tailwind...
  output: 
    | { type: 'directory', directoryPath: string }
    | { type: 'file', filePath: string };
  options?: Record<string, any>; // depends on the selected parser
}
```

{% hint style="info" %}
Looking for the parsers list and options? 👉 heads up to the [Parsers](/reference/parsers.md) reference
{% endhint %}

The object is composed of the following properties:

<table data-full-width="true"><thead><tr><th width="156.5">Name</th><th width="251">Type</th><th width="133">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>string</code></td><td><code>true</code></td><td>The name of the parser. Choose from <a href="/pages/x9NSJCFlnHujLrVNxAhg">all available parsers</a>.</td></tr><tr><td><code>options</code></td><td><pre class="language-typescript"><code class="lang-typescript">Record&#x3C;string, any>
</code></pre></td><td><code>false</code></td><td>The options relative to the parser you apply. Each parser has its own options. For further details see <a href="/pages/x9NSJCFlnHujLrVNxAhg">Parsers</a>.</td></tr><tr><td><code>output</code></td><td><code>object</code></td><td><code>false</code></td><td>The output you want the parser to generate. In most cases, a <code>file</code> or a <code>directory</code>.</td></tr></tbody></table>

## `ParsersEngineDataBox`

The parsers engine can take several input types called parsers engine data boxes. On start, the Parsers engine requires one of the data box types to be passed in as initial input.

### SDTF

```typescript
type SDTFDataBox = {
  type: "SDTF";
  graph: SpecifyDesignTokenFormat;
  metadata?:
    | {
        activeViewName: string | null;
        views: Array<{
          name: string;
          query: SDTFQuery;
        }>;
      }
    | undefined;
};
```

### SDTF Engine

```typescript
type SDTFEngineDataBox = {
    type: "SDTF Engine";
    engine: SDTFEngine;
}
```

### Specify Repository

```typescript
type SpecifyRepositoryDataBox = {
    type: "repository";
    owner: string;
    name: string;
}
```

### JSON

```typescript
type JSONDataBox = {
    type: "JSON";
    json: string | number | boolean | unknown[] | Record<string, unknown> | null;
}
```

### Vector

```typescript
type VectorDataBox = {
    type: 'vector';
    format: 'svg' | 'pdf';
    provider: 'external' | 'Specify';
    extension: {
      vector?: string, // The text representation of the SVG file
    },
}
```

### Bitmap

```typescript
type BitmapDataBox = {
    type: 'bitmap';
    format: 'png' | 'wp2' | 'avif' | 'webp' | 'jpg' | 'jxl';
    provider: 'external' | 'Specify';
    extension: {
      bitmap?: Array<number>, // The array buffer representation of the bitmap file
    },
}
```

### Asset

```typescript
type AssetDataBox = {
    type: 'asset';
    format: 'png' | 'wp2' | 'avif' | 'webp' | 'jpg' | 'jxl' | 'svg' | 'pdf' | 'ttf' | 'woff' | 'woff2' | 'otf' | 'eot';
    provider: 'external' | 'Specify' | 'Google Fonts' | 'Adobe Fonts';
}
```

## `ParserOutput`

The parsers produce different types of outputs based on your configuration and their proper capabilities. If not all the parsers accept an `output` configuration property, the ones which do always take a standardized type as input.

### File

Use case: the parser is expected to produce exactly one file.

```typescript
type FileOutput = {
  type: 'file';
  filePath: string;
}
```

Example with the `to-css-custom-properties` parser:

```json
"parsers": [
  {
    "name": "to-css-custom-properties",
    "output": {
      "type": "file",
      "filePath": "style.css"
    }
  }
]
```

### **Directory**

Use case: the parser is expected to produce 0 to N files, all placed in the given base directory.

```typescript
type DirectoryOutput = {
  type: 'directory';
  directoryPath: string;
}
```

Example with the `to-svg-file` parser:

```json
"parsers": [
  {
    "name": "to-svg-file",
    "output": {
      "type": "directory",
      "directoryPath": "./public/assets"
    }
  }
]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.specifyapp.com/reference/parsers-engine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.