> For the complete documentation index, see [llms.txt](https://yagsl.yassrobotics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yagsl.yassrobotics.com/reference/json-schema.md).

# JSON Configuration Schema

YAGSL builds a YAMS `SwerveDrive` from a directory of JSON files. `swervelib.parser.SwerveParser` reads this directory and constructs the equivalent YAMS `SwerveDriveConfig` / `SwerveModuleConfig` / `SmartMotorControllerConfig` objects for you — you rarely need to hand-edit these files, since [config.yagsl.com](https://config.yagsl.com) generates them for you, but knowing the schema is useful for debugging, scripting, or hand-tweaking a single value.

{% hint style="info" %}
If you're setting up a robot for the first time, use the [Tutorial](/tutorial/tutorial.md) section instead — this is reference material for looking up exact field names and types.
{% endhint %}

## Directory layout

```
src/main/deploy
└── swerve
    └── base                       <- name is arbitrary, passed to `new SwerveParser(...)`
        ├── swervedrive.json
        └── modules
            ├── frontleft.json
            ├── frontright.json
            ├── backleft.json
            ├── backright.json     <- module filenames are arbitrary, referenced by swervedrive.json
            ├── physicalproperties.json
            ├── pidfproperties.json
            └── pidfproperties_sim.json   (optional)
```

`SwerveParser` reads, in order:

1. `swervedrive.json` — top-level drive config: gyro + list of module files.
2. `modules/physicalproperties.json` — default gearing and current limits shared by every module.
3. `modules/pidfproperties.json` — default PID + feedforward gains shared by every module. If `modules/pidfproperties_sim.json` also exists, it's used instead whenever `RobotBase.isSimulation()` is `true`, so you can tune sim and real gains independently.
4. Each file listed in `swervedrive.json`'s `modules` array — one per swerve module, describing that module's hardware, wiring, and location. A module file may override the gearing from `physicalproperties.json` with its own `gearing` object.

All JSON is parsed with Jackson in lenient mode (`FAIL_ON_UNKNOWN_PROPERTIES = false`), so unknown fields are ignored rather than rejected — useful if you're migrating a file field-by-field.

## Pages in this section

* [swervedrive.json](/reference/json-schema/swervedrive-json.md)
* [module json (per-module file)](/reference/json-schema/module-json.md)
* [physicalproperties.json](/reference/json-schema/physicalproperties-json.md)
* [pidfproperties.json / pidfproperties\_sim.json](/reference/json-schema/pidfproperties-json.md)
* [Device type strings](/reference/json-schema/device-types.md) — every valid `type` value for gyros, motor controllers, and absolute encoders.

{% hint style="warning" %}
Coming from a pre-2026.8.05 `swerve/` directory (`imu`, `encoder`, `conversionFactors`, `controllerproperties.json`, PIDF `f`/`iz`)? See [Schema Changes](/reference/schema-changes.md) for a full migration guide.
{% endhint %}

## Control system and CAN buses

Every device's `canbus` field is just a bus name — `""` selects your control system's **default** CAN bus, and any other string must match a bus your control system actually exposes to WPILib.

{% hint style="info" %}
**2027 season note:** the roboRIO is being replaced by the SystemCore, which exposes several CAN buses natively instead of a single `rio` bus plus an optional CTRE CANivore. `canbus` isn't changing shape for this — it still just names whichever bus a device is on. Today, on a roboRIO, that's `""` for the `rio` bus, or a CANivore's configured name for CTRE devices on a CANivore. Once WPILib/vendor support for SystemCore's buses lands, do the same thing: `""` for the default bus, and the specific bus name for anything else.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://yagsl.yassrobotics.com/reference/json-schema.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.