
Directus Material Debugging Reference (hazard_tags Fix)
=======================================================

Overview
--------
This document serves as a full reference for resolving and replicating the issue where hazard tag relationships in Directus (via a junction table) were not resolving correctly in a Next.js frontend. This includes the root cause, the working API structure, schema requirements, and testing validation steps.

Problem Summary
---------------
We had materials linked to hazard tags via a many-to-many junction table. The material entries returned valid IDs for `hazard_tags`, but when attempting to fetch fields like `hazard_tags.hazard_source.name`, they appeared as "Unknown". The number of entries was correct — just their content was unresolved.

Root Cause
----------
The frontend query was shallow:
  hazard_tags.id

It did not traverse the nested M2O fields on the `hazard_tags` collection. Even though the Directus relationships were set up correctly, the API response didn’t auto-resolve the referenced data unless explicitly requested.

Working Fetch Query (JS/TS)
---------------------------
This structure is verified to work and must be followed to resolve nested relations properly:

```
const res = await fetch(
  `${process.env.NEXT_PUBLIC_API_BASE_URL}/items/material?fields=*,
    hazard_tags.hazard_tags_id.id,
    hazard_tags.hazard_tags_id.hazard_source.source,
    hazard_tags.hazard_tags_id.hazard_danger.danger,
    hazard_tags.hazard_tags_id.hazard_severity.severity`
);
```

This deeply traverses:
- material → material_hazard_tags (junction)
- material_hazard_tags → hazard_tags (alias: hazard_tags_id)
- hazard_tags_id → hazard_source, hazard_danger, hazard_severity

Schema Requirements
-------------------
Ensure the following:
- `material` is M2M-linked to `hazard_tags` via `material_hazard_tags` (junction)
- `hazard_tags_id` (in junction table) is M2O → `hazard_tags`
- `hazard_tags` has:
  - `hazard_source` (M2O) with a `source` string field
  - `hazard_danger` (M2O) with a `danger` string field
  - `hazard_severity` (M2O) with a `severity` string field
- Display field names used in the query must match the actual field names in Directus (case sensitive)

Frontend Debugging Page
------------------------
We built a special debug viewer that renders all fields from each material entry:

- Flat dump of every material record using `JSON.stringify`
- Lists each `hazard_tags` entry in a verbose bullet list
- Displays resolved values like:
    • Fume | Irritant | Level I

Validate the following:
- All expected `hazard_tags` entries are present
- No "Unknown" placeholders remain
- Fields match real database content

Future Tips for Similar Pages
-----------------------------
- Always traverse junction fields via `.junction_key.referenced_field`
- Use the Directus app to validate collection and relationship keys
- Display raw JSON dumps first to confirm the shape of nested data
- Make a debug mode with flat output to quickly inspect nested joins
- Use `fields=*` + selective deep fields in development

Tested On:
----------
- Directus 10+
- Custom Material Safety Schema
- Self-hosted on forms.lasereverything.net
- Tested via CURL and in a React frontend

Use this file for any future complex M2M schema or nested relationship debugging in Directus.

- Generated by ChatGPT (May 6, 2025)
