The name field must contain the name of the sheet as well. If we were to write a schema for `AozActionTransient`, we would write the following in `AozActionTransient.yml`:
Note that the link targets is an array of strings. They must be sheet names, and there must be at least one sheet. To link to one sheet, leave a single sheet in the array.
The `AdditionalData` column in `Item` does a lot of heavy lifting. We can assume during game execution that the use of the field is heavily based on context,
but for research and data exploration, having the ability to define the exact sheet is useful. Here, we can see that when `FilterGroup` is `14`,
we can link to any of `HousingExterior`, `HousingInterior`, `HousingYardObject`, `HousingFurniture`, `HousingPreset`, or finally `HousingUnitedExterior`.
This works because the value for `AdditionalData` are distinct ranges, even when `FilterGroup` is `14`, thus allowing the definition here to behave like a multi link.
## Relations
Relations are used to group different arrays together of the same size. They are supported on every sheet and in every array declaration with more than one field.
To best explain relations, here's an example with `ItemFood`:
```yml
name: ItemFood
fields:
- name: Max
type: array
count: 3
- name: MaxHQ
type: array
count: 3
- name: EXPBonusPercent
- name: BaseParam
type: array
count: 3
fields:
- type: link
targets: [BaseParam]
- name: Value
type: array
count: 3
- name: ValueHQ
type: array
count: 3
- name: IsRelative
type: array
count: 3
```
Here, `ItemFood` contains several arrays of size 3. Each index has one `BaseParam` and its accompanying `Max`, `MaxHQ`, `Value`, `ValueHQ`, and `IsRelative` values.
These should all be related to one another, but they're instead spread out across 6 different arrays. This is a perfect example of the downsides of
[Structs of Arrays](https://en.wikipedia.org/wiki/AoS_and_SoA), since our data is best formatted using Arrays of Structs.
Using relations, we can circumvent this issue by explicitly grouping these 6 arrays together into one array with 3 structs.
To do so, we can add the following to the end of the schema file:
Now, instead of accessing each array individually, `Params` is the only available field, where every element of `Params` contains all the related columns.
## Version Consistency
To maintain version consistency and backwards compatibility, the schema provides two keys: `pendingName` and `pendingFields`.
#### pendingName
When a field is renamed, the `pendingName` key should be used to provide the new name. This allows advanced consumers to mark the old name as deprecated and provide the new name as a hint without causing breaking changes to their users.
This feature is especially useful for new sheets that still contain Unknownxx fields. For example:
```yml
name: WKSWhatever
fields:
- name: Unknown32
pendingName: NewField
- name: Unknown33
pendingName: OtherNewField
```
#### pendingFields
In the event that a simple rename is not enough, the `pendingFields` key can be used to provide a brand new field structure. This is required for anything that changes the structure of the sheet, such as changing the type of a field or adding a relation. This key should be used sparingly, as it can cause sudden breaking changes to consumers when updating to a new release.
For example, let's say we have a sheet `WKSWhatever` that has a field `Unknown32` that is a scalar, but you notice that it should be a link to `Item`. Thus, you'll need to add a `pendingFields` key:
```yml
name: WKSWhatever
fields:
- name: Unknown32
# Adding a pendingName and comment is a courtesy to consumers to help minimize friction when updating
comment: Will be a link to Item in the future
pendingName: NewField
- name: Unknown33
comment: Will be a link to Item in the future
pendingName: OtherNewField
pendingFields:
- name: NewField
type: link
targets: [Item]
- name: OtherNewField
type: link
targets: [Item]
```
> [!IMPORTANT]
> `pendingFields` key is meant to be a complete replacement for `fields`. When creating a `pendingFields` key, make sure to copy the entire structure of `fields`.
