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

# Materials

> The property tables that give a material its identity — substance, form, dimension, finish, grade, and type.

A **material** is an [item](/docs/reference/items.md) of type *Material* used as raw stock. Structured property tables define its **substance**, **form**, **dimension**, and optional **finish**, **grade**, and **type**. Alforse uses these values to generate the material's identity, display name, and code.

A material references these lookups by id: `materialSubstanceId`, `materialFormId`, `dimensionId`, `finishId`, `gradeId`, and `materialTypeId`. Only substance and form are required when ids are generated (see below), so a material can be as loosely or tightly specified as you need.

## The property tables

Six lookup tables compose a material. **Substance** and **form** are independent; the remaining choices are scoped by one or both and therefore cascade.

FieldType

<details>
  <summary>**Substance**`materialSubstance`</summary>

  What the material is made of: steel, aluminum, stainless, titanium. Has a `name` and a `code`.
</details>

<details>
  <summary>**Form**`materialForm`</summary>

  Its shape or product form: sheet, plate, round bar, ingot. Has a `name` and a `code`.
</details>

<details>
  <summary>**Dimension**`materialDimension`</summary>

  A named size, scoped to a **form** (a sheet's dimension list differs from a bar's). Carries `isMetric`.
</details>

<details>
  <summary>**Finish**`materialFinish`</summary>

  A surface finish, scoped to a **substance**.
</details>

<details>
  <summary>**Grade**`materialGrade`</summary>

  A material grade, scoped to a **substance** (for example a steel grade like 1018).
</details>

<details>
  <summary>**Type**`materialType`</summary>

  A named product type keyed to a **substance and a form** together, such as hot-rolled steel plate. Has a `name` and a `code`.
</details>

NOTE

**The lookups cascade**

Substance and form stand alone. **Grade** and **finish** are picked from the list for the chosen substance; **dimension** from the list for the chosen form; **type** from the intersection of both. Change the substance and the grade or finish list you can pick from changes with it. This is why the material form on new-material screens fills top down.

## Scope: system-wide or per company

Alforse provides a starter taxonomy. System values live in `materialStandardDefinition` and are visible to every company; a company's own additions live in `materialCompanyDefinition`. Both tables hold all six kinds in one place, distinguished by `definitionKind` (*substance*, *form*, *type*, *grade*, *finish*, *dimension*).

FieldType

<details>
  <summary>**Substance, form**`definitionKind`</summary>

  Carry a required `code` (up to 10 characters: uppercase letters, digits, hyphen) and a name.
</details>

<details>
  <summary>**Dimension**`definitionKind`</summary>

  Scoped to a **form**; carries `isMetric`.
</details>

<details>
  <summary>**Finish, grade**`definitionKind`</summary>

  Scoped to a **substance**.
</details>

<details>
  <summary>**Type**`definitionKind`</summary>

  Scoped to a **substance and a form** together.
</details>

NOTE

**Uniqueness**

Within a company, a definition is unique by kind, name (case-insensitive), code, and its substance and form scope, so the same name can appear under different forms or substances but not twice under the same parent. Edits go through an idempotent command log (`materialDefinitionCommand`).

## How a material references them

A material is an item of type *Material*. Its readable id is its material id, so a material's part number *is* its material id. The material form's **Material ID** field is shown only when auto-generation is off (see Troubleshooting).

One material can span several item records: separate **revisions**, and a separate item per stock size. The `sizes` you assign become selectable variants on [jobs](/docs/reference/jobs.md) and purchase orders, each its own item row sharing the material's id.

NOTE

**Only substance and form are required to generate a material**

When Alforse generates the material and its ids, `materialSubstanceId` and `materialFormId` are required; dimension, finish, grade, and type are optional. A material is minimally "a substance in a form" and everything else refines it.

## Naming and uniqueness

Alforse composes a material's display name from substance, form, and optional finish, grade, and dimension names. Substance, form, and type codes compose the material code. Property combinations provide a structured identity rather than relying on free text.

Because dimensions belong to forms and grades and finishes belong to substances, a valid material is always an internally consistent set of choices. You cannot pick a bar dimension for a sheet, or a stainless grade for aluminum, because those lists are filtered to the parent you already chose.

## Related

**Items**

A material is an item of type *Material*; item fields like tracking and unit of measure live here.

[Open](/docs/reference/items.md)

**Methods & sourcing**

Materials become the components of a method's bill of materials.

[Open](/docs/reference/methods.md)


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