Material Schema Specification

Version: 1.0 Status: Implemented – yapCAD 1.0 Date: December 2025

Overview

This specification defines how materials are represented in yapCAD packages. The design prioritizes engineering data over visual styling, enabling:

FEA/simulation integration
Manufacturing process planning
Bill of materials generation
Standards compliance tracking

Visual properties for rendering are secondary and derived from or associated with material definitions.

Design Principles

Standards-First: Reference industry standards (AA, ASTM, SAE, ISO) when available
Engineering Data: Physical properties are primary; visual properties are auxiliary
Traceability: Materials link to sources (standards bodies, vendors, test data)
Extensibility: Custom properties can be added without breaking compatibility
Separation of Concerns: Layers organize geometry; materials define substance

Schema Structure

Package Manifest Integration

Materials are defined in the package manifest under a materials key:

# manifest.yaml
name: "bracket-assembly"
version: "1.0.0"
units: "mm"

materials:
  aluminum_6061:
    # ... material definition
  pla_black:
    # ... material definition

geometry:
  primary:
    path: "geometry/assembly.json"

Alternatively, materials may be defined in a separate file:

# manifest.yaml
materials:
  path: "materials.yaml"  # External file reference

Material Definition Schema

material_id:                    # Unique identifier within package
  # === Source Information (required) ===
  source:
    type: "standard" | "vendor" | "custom" | "tested"

    # For type: "standard"
    standard:
      body: "AA" | "ASTM" | "SAE" | "ISO" | "DIN" | "JIS" | ...
      designation: "6061-T6"    # Standard's material designation
      revision: "2023"          # Optional: standard revision/year

    # For type: "vendor"
    vendor:
      name: "Prusament"
      product_id: "PLA Galaxy Black"
      lot: "2024-Q3"            # Optional: lot/batch
      url: "https://..."        # Optional: product page
      datasheet: "datasheets/prusament_pla.pdf"  # Optional: local copy

    # For type: "tested"
    tested:
      lab: "Internal QA"
      date: "2024-11-15"
      report: "test_reports/al_batch_42.pdf"

    # For type: "custom"
    custom:
      author: "J. Smith"
      notes: "Estimated properties for prototype"

  # === Material Classification (recommended) ===
  classification:
    category: "metal" | "polymer" | "ceramic" | "composite" | "other"
    family: "aluminum" | "steel" | "titanium" | "thermoplastic" | ...

  # === Physical Properties (required for engineering use) ===
  properties:
    # Density
    density:
      value: 2.70
      unit: "g/cm3"

    # Mechanical - Elastic
    elastic_modulus:
      value: 68.9
      unit: "GPa"
    poisson_ratio:
      value: 0.33

    # Mechanical - Strength
    yield_strength:
      value: 276
      unit: "MPa"
      condition: "0.2% offset"  # Optional: test condition
    ultimate_tensile_strength:
      value: 310
      unit: "MPa"
    elongation:
      value: 12
      unit: "%"

    # Thermal
    thermal_conductivity:
      value: 167
      unit: "W/(m*K)"
    specific_heat:
      value: 896
      unit: "J/(kg*K)"
    melting_point:
      value: 582
      unit: "C"
      note: "Solidus"
    thermal_expansion:
      value: 23.6e-6
      unit: "1/K"

    # Electrical (optional)
    electrical_resistivity:
      value: 3.99e-8
      unit: "ohm*m"

    # Custom properties
    custom:
      hardness_brinell:
        value: 95
        unit: "HB"

  # === Manufacturing Constraints (optional) ===
  manufacturing:
    processes:
      - type: "CNC_milling"
        notes: "Good machinability"
      - type: "welding"
        method: "TIG"
        filler: "4043"

    # For additive manufacturing
    additive:
      process: "FDM" | "SLA" | "SLS" | "DMLS" | ...
      nozzle_temp: [200, 220]   # Range in C
      bed_temp: [50, 60]
      chamber_temp: null
      layer_height: [0.1, 0.3]  # Range in mm

  # === Visual Properties (for rendering) ===
  visual:
    # Base color (RGB, 0-1 range)
    color: [0.75, 0.78, 0.80]

    # PBR material properties
    metallic: 0.9              # 0 = dielectric, 1 = metal
    roughness: 0.3             # 0 = mirror, 1 = diffuse

    # Optional: more detailed appearance
    appearance:
      finish: "brushed" | "polished" | "matte" | "textured"
      anodized: false
      anodize_color: null

    # Optional: texture references
    textures:
      albedo: "textures/brushed_aluminum.png"
      normal: "textures/brushed_aluminum_normal.png"
      roughness: "textures/brushed_aluminum_rough.png"

Compact Form for Simple Cases

For quick prototyping or when full data isn’t needed:

materials:
  generic_aluminum:
    source:
      type: "standard"
      standard: { body: "AA", designation: "6061-T6" }
    properties:
      density: { value: 2.70, unit: "g/cm3" }
    visual:
      color: [0.75, 0.78, 0.80]
      metallic: 0.9
      roughness: 0.3

Minimal Form (Visual Only)

When physical properties aren’t needed:

materials:
  display_blue:
    source:
      type: "custom"
      custom: { notes: "Visual placeholder" }
    visual:
      color: [0.2, 0.4, 0.8]
      metallic: 0.0
      roughness: 0.5

Geometry Association

Materials are associated with solids via metadata:

{
  "entities": [
    {
      "type": "solid",
      "id": "bracket_001",
      "metadata": {
        "material": "aluminum_6061",
        "layer": "structural",
        "name": "Main Bracket"
      },
      "shell": ["surface_001", "surface_002"]
    }
  ]
}

Association Rules

Solid-level: Each solid may have one material assignment
Inheritance: If no material specified, inherit from parent assembly
Override: Child components can override parent material
Null material: Explicit "material": null means unspecified (rendered with default)

Built-in Material Library

yapCAD ships with a standard material library for common engineering materials:

Metals

ID	Standard	Description
`AA-6061-T6`	AA 6061-T6	General purpose aluminum
`AA-7075-T6`	AA 7075-T6	High strength aluminum
`AISI-304`	AISI 304	Austenitic stainless steel
`AISI-316`	AISI 316	Marine grade stainless
`Ti-6Al-4V`	AMS 4911	Titanium alloy

Polymers - 3D Printing

ID	Type	Description
`PLA-generic`	PLA	Standard PLA filament
`ABS-generic`	ABS	Standard ABS filament
`PETG-generic`	PETG	Standard PETG filament
`Nylon-PA12`	PA12	Nylon 12
`Resin-standard`	SLA	Generic photopolymer resin

Polymers - Engineering

ID	Standard	Description
`Delrin-150`	ASTM D4181	Acetal homopolymer
`PEEK-natural`	-	Polyetheretherketone
`UHMWPE`	ASTM D4020	Ultra-high MW polyethylene

Usage

materials:
  bracket_material:
    extends: "AA-6061-T6"  # Inherit from built-in
    visual:
      color: [0.8, 0.2, 0.2]  # Override color only

Renderer Integration

Material Resolution

The viewer resolves materials in this order:

Check solid’s metadata.material reference
Look up in package materials dictionary
If extends present, merge with built-in library
Fall back to default material if not found

Visual Property Mapping

Schema Property	OpenGL/Shader Use
`visual.color`	Diffuse color (with lighting)
`visual.metallic`	Fresnel F0 calculation
`visual.roughness`	Specular spread

Default Material

When no material is specified:

_default:
  visual:
    color: [0.6, 0.85, 1.0]  # Current yapCAD blue
    metallic: 0.0
    roughness: 0.5

Validation Rules

Required fields: source.type must be present
Standard references: If source.type: "standard", must have source.standard.body and source.standard.designation
Property units: All physical properties should include units
Color range: RGB values must be in [0, 1]
PBR range: metallic and roughness must be in [0, 1]

Future Extensions

Planned (Priority)

Integration with external material databases (MatWeb, Granta, manufacturer APIs)
Anisotropic materials (fiber composites, wood, etc.)
Composite layup definitions (ply orientation, stacking sequence)

Planned

Material cost data for BOM generation
Environmental/sustainability properties
Temperature-dependent properties
Material testing workflow integration
Certification/compliance tracking

Examples

Example 1: CNC Machined Part

materials:
  bracket_al:
    source:
      type: "standard"
      standard:
        body: "AA"
        designation: "6061-T6"
    classification:
      category: "metal"
      family: "aluminum"
    properties:
      density: { value: 2.70, unit: "g/cm3" }
      yield_strength: { value: 276, unit: "MPa" }
      elastic_modulus: { value: 68.9, unit: "GPa" }
    manufacturing:
      processes:
        - type: "CNC_milling"
        - type: "anodizing"
          color: "black"
    visual:
      color: [0.1, 0.1, 0.1]
      metallic: 0.8
      roughness: 0.2

Example 2: 3D Printed Prototype

materials:
  prototype_pla:
    source:
      type: "vendor"
      vendor:
        name: "Hatchbox"
        product_id: "PLA 1.75mm Black"
    classification:
      category: "polymer"
      family: "thermoplastic"
    properties:
      density: { value: 1.24, unit: "g/cm3" }
      yield_strength: { value: 50, unit: "MPa", condition: "printed, 100% infill" }
    manufacturing:
      additive:
        process: "FDM"
        nozzle_temp: [200, 215]
        bed_temp: [55, 65]
        layer_height: [0.12, 0.28]
    visual:
      color: [0.05, 0.05, 0.05]
      metallic: 0.0
      roughness: 0.7

Example 3: Multi-Material Assembly

materials:
  housing_abs:
    source:
      type: "vendor"
      vendor: { name: "PolyMaker", product_id: "PolyLite ABS" }
    properties:
      density: { value: 1.04, unit: "g/cm3" }
    visual:
      color: [0.2, 0.2, 0.25]
      metallic: 0.0
      roughness: 0.4

  insert_brass:
    source:
      type: "standard"
      standard: { body: "ASTM", designation: "B16" }
    properties:
      density: { value: 8.47, unit: "g/cm3" }
    visual:
      color: [0.78, 0.57, 0.11]
      metallic: 1.0
      roughness: 0.35

{
  "entities": [
    {
      "type": "solid",
      "id": "housing",
      "metadata": { "material": "housing_abs", "layer": "enclosure" }
    },
    {
      "type": "solid",
      "id": "thread_insert_1",
      "metadata": { "material": "insert_brass", "layer": "hardware" }
    }
  ]
}

Changelog

0.1 (2025-11): Initial draft