> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File Structure

> How to organize connector files using partial files and suggested naming conventions.

Connectors are organized into a **main connector file** and, optionally, **partial files**. Partial files can be used to split large connectors up into more manageable chunks for maintenance and are consumed in the StackOne platform as if it were a single configuration file.

## Best practices

For maintaining connectors for development, use the directory structure below:

```
connectors/{provider}/
├── {provider}.connector.s1.yaml            # Main connector file (authentication, metadata)
├── {provider}.{resourceA}.s1.partial.yaml  # Partial file (actions grouped by resourceA)
├── {provider}.{resourceB}.s1.partial.yaml  # Partial file (actions grouped by resourceB)
└── {provider}.events.s1.partial.yaml       # Partial file (event handlers - if available)
```

### Main connector file

The main connector file defines the top-level properties (see [YAML Schema](/connector-yaml-reference/yaml-schema/overview)): connector metadata, authentication, and an `actions` block (plus an `events` block for webhooks) that reference the partial files.

Partial files are referenced in the main file by the filename without the `.s1.partial.yaml` extension.

<Warning>Parital files must be within the same folder as the main connector file.</Warning>

```yaml theme={null}
# acme.connector.s1.yaml
StackOne: 1.0.0
...
actions:
  - $ref: acme.employees  # references acme.employees.s1.partial.yaml
  - $ref: acme.departments  # references acme.departments.s1.partial.yaml

events:
  setup: {...}
  router: {...}
  externalAccountIdExtractor: {...}
  actions:
    - $ref: acme.events  # references acme.events.s1.partial.yaml
```

<Tip>Add references in alphabetical order for readability.</Tip>

### Partial files

Each partial file is a group of actions, e.g. grouped per resource.

```yaml theme={null}
# acme.employees.s1.partial.yaml
- actionId: list_employees
  ...

- actionId: get_employee
  ...
```

```yaml theme={null}
# acme.departments.s1.partial.yaml
- actionId: list_departments
  ...

- actionId: get_department
  ...
```

Event handlers are grouped the same way:

```yaml theme={null}
# acme.events.s1.partial.yaml
- actionId: employee_created
  actionType: event
  ...

- actionId: employee_updated
  actionType: event
  ...
```

## Related

<CardGroup cols={2}>
  <Card title="YAML Schema" icon="gear" href="/connector-yaml-reference/yaml-schema/overview">
    Full YAML schema for building connectors with field tables and examples.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.