Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 79 additions & 1 deletion docs/manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ A filament represents a **product line** (e.g. "Silk PLA", "Glow PLA"), **not a
- Documents: `data_sheet_url`, `safety_sheet_url`
- Lifecycle: `discontinued` (boolean)
- Slicer integration: `slicer_ids` (PrusaSlicer / BambuStudio / OrcaSlicer / Cura native IDs) and `slicer_settings` (per-slicer profile names, IDs, and temperature overrides)
- Sustainability: `sustainability` — sourced recycled / bio-based content, carbon footprints and relative claims. See [🌱 Sustainability data](#-sustainability-data); every figure needs a source.

## 🎨 Adding a Variant
A variant represents a single colour or finish of a filament.
Expand Down Expand Up @@ -148,6 +149,7 @@ Inside the filament folder, create a folder named with the variant `id` (e.g. `l
- `hex_variants` — array of alternative `#RRGGBB` codes the filament is known to report (e.g. via NFC)
- `transmission_distance` — number, mm; the transmission distance (TD) used for HueForge prints and lithophanes. Use the manufacturer's published value where available
- `color_standards` — object with any of `ral`, `ncs`, `pantone`, `bs`, `munsell`
- `sustainability` — overrides the filament's `sustainability` **per field** (see [🌱 Sustainability data](#-sustainability-data))
- `traits` — **an object** mapping trait names to booleans, **not** an array of strings. Available traits include `silk`, `matte`, `glow`, `translucent`, `transparent`, `recycled`, `biodegradable`, `abrasive`, `glitter`, `iridescent`, `temperature_color_change`, `gradual_color_change`, `coextruded`, the `contains_*` family (carbon, glass, wood, metal, …), the `imitates_*` family, `esd_safe`, `self_extinguishing`, and many more. See the schema for the complete enumeration.

### sizes.json
Expand All @@ -166,7 +168,8 @@ A JSON **array** of one or more size objects. At minimum:
- Spool geometry: `empty_spool_weight`, `spool_core_diameter`, `container_width`, `container_outer_diameter`, `container_hole_diameter`
- Identifiers: `gtin` (GTIN-12 or GTIN-13 — preferred), `ean` (deprecated alias for `gtin`), `article_number`, `barcode_identifier`, `nfc_identifier`, `qr_identifier`
- `spool_refill` — (deprecated) boolean; use `container_material: refill` instead
- `container_material` — one of `plastic`, `cardboard`, `refill`; what the container is made of
- `container_material` — one of `plastic`, `cardboard`, `mixed` (e.g. a cardboard core with plastic sides), `refill`; what the container is made of
- `container_details` — sourced details about this size's spool or packaging: `recycled_pct`, `pct_qualifier`, `certifications` (e.g. `["FSC"]`), `notes`, plus the source fields described in [🌱 Sustainability data](#-sustainability-data). Per size, because some brands use cardboard spools on certain sizes only.
- `discontinued` — boolean
- `purchase_links` — array of purchase entries:
- `store_id` — required; must match a folder under `/stores`
Expand All @@ -175,6 +178,81 @@ A JSON **array** of one or more size objects. At minimum:

> **Note:** there is no `is_affiliate` field on purchase links. Affiliate handling is implicit in the store entry and the URL itself.

## 🌱 Sustainability data
Sustainability figures are used to calculate the CO₂ footprint of prints, and they get copied into consumer-facing material. So they follow stricter rules than the rest of the database.

### The rules
1. **Copy, never compute.** Every number must appear in the source exactly as entered. Never derive, average, convert units or estimate. If the unit or scope is unclear, use `unknown`; never guess.
2. **Every entry needs a source**: `source_url`, `source_quote` (verbatim text that contains the number; `5.85` and `5,85` both match) and `retrieved` (the date you read it, `YYYY-MM-DD`). No source, no entry.
3. **Primary sources first**: the brand's own site, PDF, blog or declaration. A retailer or press copy of the brand's text is allowed only when the original can't be reached; mark it `source_type: "secondary"`.
4. **Never store** offsets or tree planting, "carbon neutral" / "climate neutral" / "CO₂ neutral", "eco-friendly", "most sustainable", or biodegradability marketing. The EU Empowering Consumers Directive bans offset-based and generic green claims, and these fields end up in consumer marketing. The schema has nowhere to put them on purpose.
5. **No estimates in `data/`.** Generic per-material defaults are a different kind of data and live in [`reference/`](../reference), never in a brand's filament.
6. **Recycled content needs the trait.** `recycled_content.pct > 0` requires `traits.recycled: true` on the affected variants (an error otherwise). The reverse only warns, and only once the filament or variant has a `sustainability` block.

`ofd validate` enforces rules 2, 6 and the number-in-quote part of rule 1, and rejects percentages outside 0–100 and dates in the future.

### Where it goes
`sustainability` can sit on `filament.json` and on `variant.json`. A variant overrides the filament **per field**: if a variant sets `recycled_content`, that replaces the filament's `recycled_content`; if it sets `carbon_footprints`, that array replaces the filament's array as a whole. Fields the variant doesn't set are inherited. Spool and packaging details go on each size in `sizes.json` as `container_details`.

```json
"sustainability": {
"recycled_content": {
"pct": 100, "pct_qualifier": "exact",
"type": "post_industrial", "evidence": "supplier_declaration",
"source_type": "primary",
"source_url": "https://blog.prusa3d.com/introducing-prusament-pla-recycled_59116/",
"source_quote": "…100 % of recycled Prusament PLA materials…",
"retrieved": "2026-10-21"
},
"carbon_footprints": [{
"value_kg_co2e": 5.85, "declared_unit": "per_kg_filament",
"boundary": "filament_cradle_to_gate", "packaging_included": "unknown",
"biogenic_carbon": "unknown", "recycled_allocation": "not_applicable",
"method": "lca", "tool": "SimaPro 9.3.0.2", "verification": "none",
"publicly_available": true, "published": "2022-03-17",
"source_type": "primary", "source_url": "https://blog.prusa3d.com/…",
"source_quote": "The results show 5.85 kg of CO2 with 1kg of pure Prusament PETG",
"retrieved": "2026-10-21"
}]
}
```

### Field guide
| Field | Values | Meaning |
|---|---|---|
| `recycled_content.pct` | 0–100 or `null` | `null` when the source says "recycled" but gives no number |
| `pct_qualifier` | `exact`, `up_to`, `at_least` | "up to 89%" is `up_to`, "90–100%" is `at_least` 90 |
| `recycled_content.type` | `post_industrial`, `post_consumer`, `mixed`, `unknown` | Manufacturing scrap vs. used products. Use `unknown` when sources conflict, and quote both in `notes` |
| `evidence` | `iso_14021`, `third_party_certified`, `supplier_declaration`, `marketing` | `iso_14021` only when the source cites ISO 14021; GRS/RCS/SCS certificates are `third_party_certified` |
| `bio_based_content.method` | `astm_d6866`, `en_16785`, `declared` | Bio-based **pigments or additives are not bio-based content** |
| `declared_unit` | `per_kg_filament`, `per_spool_as_sold`, `unknown` | What the number refers to. Use `unknown` if the source doesn't say "per kg" |
| `boundary` | see below | Which life-cycle stages the number covers |
| `packaging_included` | `yes`, `no`, `unknown` | Whether spool, box and bag are inside the number |
| `biogenic_carbon` | `included`, `excluded`, `reported_separately`, `unknown` | How carbon absorbed by plants is counted |
| `recycled_allocation` | `cut_off`, `burden_free_scrap`, `other`, `unknown`, `not_applicable` | How recycled input is credited; `not_applicable` for virgin material |
| `method` | `epd`, `iso_14067`, `lca`, `declaration` | `declaration` is a figure with no published study behind it |
| `standard` | free text or `null` | **Only** when the source names one, e.g. "ISO 14067" |
| `verification` | `none`, `peer_review`, `third_party`, `epd_registered` | Independent review of the study |
| `publicly_available` | boolean | `false` when the study is "available on request" |
| `relative_claims[].baseline` | free text | Verbatim, e.g. "generic PET filament" |

**Boundaries:**
- `resin_cradle_to_gate`: making the raw plastic only, before it becomes filament.
- `filament_cradle_to_gate`: from raw materials up to filament leaving the factory.
- `cradle_to_customer`: also includes delivery to the buyer.
- `cradle_to_grave`: the full life cycle, including end of life.

**Relative claims** (`relative_claims`) are for brands that only publish "X% lower than …". Store the percentage and the baseline exactly as written, and never turn them into an absolute number.

### Valid sources
- ✅ The brand's product page, datasheet, sustainability page, blog post, LCA report or EPD
- ✅ A retailer or press copy of the brand's own text, **only** when the original is gone (`source_type: "secondary"`)
- ❌ A company-wide footprint (e.g. an ISO 14064-1 corporate report) as a product figure
- ❌ Figures you calculated, averaged or converted
- ❌ Anything from the "never store" list above

Checked a brand and found nothing? Record that in [`docs/sustainability-sources.md`](sustainability-sources.md). A negative result is useful too.

## 🏪 Adding a Store
Stores are referenced by `purchase_links[].store_id` and live under `/stores`.

Expand Down
15 changes: 15 additions & 0 deletions docs/sustainability-sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Sustainability sources log

One row per brand checked for sustainability data (see [🌱 Sustainability data](manual.md#-sustainability-data)), including brands where **nothing was published**. A negative result saves the next person the same search.

When you check a brand, add or update its row. Keep rows in alphabetical order by brand id.

| Brand | Checked | Found | Sources |
|---|---|---|---|

## Open questions for brands

Questions to raise with brands where the published data is ambiguous. Remove an item once it has been answered and the data has been updated.

| Brand | Question | Affects |
|---|---|---|
50 changes: 50 additions & 0 deletions ofd/builder/exporters/api_exporter.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@
import uuid
from pathlib import Path

from jsonschema import Draft7Validator
from referencing import Registry, Resource
from referencing.jsonschema import DRAFT7

from ..models import Database
from ..serialization import entity_to_dict

Expand Down Expand Up @@ -296,6 +300,41 @@ def export_store_logos(
return copied_count, logo_id_mapping


def export_material_defaults(api_path: Path, reference_dir: Path, schemas_dir: Path) -> bool:
"""
Publish reference/material_defaults.json as api/v1/material-defaults.json.

These are generic per-material estimates, not manufacturer data, so they live outside
data/ and are published as their own artifact. The file is validated against
material_defaults_schema.json first; an invalid file fails the build.
"""
src = reference_dir / "material_defaults.json"
if not src.exists():
return False

with open(src, encoding="utf-8") as f:
defaults = json.load(f)

schema_path = schemas_dir / "material_defaults_schema.json"
if schema_path.exists():
with open(schema_path, encoding="utf-8") as f:
schema = json.load(f)
# Register every schema by its "./name" so cross-file $refs resolve.
registry = Registry().with_resources(
(
f"./{p.name}",
Resource.from_contents(
json.loads(p.read_text(encoding="utf-8")), default_specification=DRAFT7
),
)
for p in schemas_dir.glob("*_schema.json")
)
Draft7Validator(schema, registry=registry).validate(defaults)

shutil.copy2(src, api_path / "material-defaults.json")
return True


def export_api(
db: Database,
output_dir: str,
Expand All @@ -307,6 +346,7 @@ def export_api(
data_dir: str = "data",
stores_dir: str = "stores",
commit: str | None = None,
reference_dir: str | None = None,
**kwargs,
):
"""Export static API structure following native directory hierarchy."""
Expand All @@ -333,6 +373,14 @@ def export_api(
trait_rules_written = True
print(f" Written: {api_path / 'trait-rules.json'}")

material_defaults_written = False
if reference_dir and schemas_dir:
material_defaults_written = export_material_defaults(
api_path, Path(reference_dir), Path(schemas_dir)
)
if material_defaults_written:
print(f" Written: {api_path / 'material-defaults.json'}")

# Export brand and store logos (get logo ID mappings)
data_path = Path(data_dir)
stores_path = Path(stores_dir)
Expand Down Expand Up @@ -378,6 +426,8 @@ def export_api(
# Only advertised when actually written, so the index can never point at a 404.
if trait_rules_written:
endpoints["trait_rules"] = "trait-rules.json"
if material_defaults_written:
endpoints["material_defaults"] = "material-defaults.json"

index = {
"version": version,
Expand Down
3 changes: 3 additions & 0 deletions ofd/builder/exporters/csv_exporter.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@
"dry_time",
"enclosure",
"discontinued",
"sustainability",
],
"variant": [
"id",
Expand All @@ -67,6 +68,7 @@
"color_standards",
"traits",
"discontinued",
"sustainability",
# moved_from is a conditional key that would otherwise sort after color_hexes
"moved_from",
"color_hexes",
Expand All @@ -80,6 +82,7 @@
"empty_spool_weight",
"spool_core_diameter",
"container_material",
"container_details",
"gtin",
"article_number",
"discontinued",
Expand Down
9 changes: 6 additions & 3 deletions ofd/builder/exporters/sqlite_exporter.py
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,8 @@
data_sheet_url TEXT,
safety_sheet_url TEXT,
discontinued INTEGER NOT NULL DEFAULT 0,
slicer_settings TEXT -- JSON
slicer_settings TEXT, -- JSON
sustainability TEXT -- JSON (see schemas/sustainability_schema.json)
);
CREATE INDEX IF NOT EXISTS ix_filament_brand ON filament(brand_id);
CREATE INDEX IF NOT EXISTS ix_filament_material ON filament(material_id);
Expand All @@ -111,7 +112,8 @@
transmission_distance REAL, -- mm
color_standards TEXT, -- JSON
traits TEXT, -- JSON
discontinued INTEGER NOT NULL DEFAULT 0
discontinued INTEGER NOT NULL DEFAULT 0,
sustainability TEXT -- JSON; per-field override of the filament's
);
CREATE INDEX IF NOT EXISTS ix_variant_filament ON variant(filament_id);
CREATE INDEX IF NOT EXISTS ix_variant_slug ON variant(slug);
Expand All @@ -127,7 +129,8 @@
diameter REAL NOT NULL,
empty_spool_weight INTEGER,
spool_core_diameter REAL,
container_material TEXT, -- plastic | cardboard | refill
container_material TEXT, -- plastic | cardboard | mixed | refill
container_details TEXT, -- JSON
gtin TEXT,
article_number TEXT,
barcode_identifier TEXT,
Expand Down
2 changes: 2 additions & 0 deletions ofd/commands/build.py
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,7 @@ def run_build(args: argparse.Namespace) -> int:
data_dir = project_root / args.data_dir
stores_dir = project_root / args.stores_dir
schemas_dir = project_root / "schemas"
reference_dir = project_root / "reference"
builder_schemas_dir = Path(__file__).parent.parent / "builder" / "schemas"
output_dir = project_root / args.output_dir

Expand Down Expand Up @@ -219,6 +220,7 @@ def run_build(args: argparse.Namespace) -> int:
data_dir=str(data_dir),
stores_dir=str(stores_dir),
commit=commit,
reference_dir=str(reference_dir),
)
else:
print("\n[6/11] Skipping Static API export")
Expand Down
17 changes: 12 additions & 5 deletions ofd/scripts/export_data.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
from jsonschema.exceptions import ValidationError as JsonSchemaValidationError
from jsonschema.validators import Draft7Validator
from referencing import Registry, Resource
from referencing.jsonschema import DRAFT7

from ofd.base import BaseScript, ScriptResult, register_script

Expand Down Expand Up @@ -99,12 +100,18 @@ def get(self, name: str) -> dict | None:
def registry(self) -> Registry:
"""Get schema registry for $ref resolution."""
if self._registry is None:
material_types = self.get("material_types")
# Register every schema by its "./name" so cross-file $refs
# (material_types, sustainability, ...) resolve.
resources = []
if material_types:
resources.append(
("./material_types_schema.json", Resource.from_contents(material_types))
)
for path in sorted(self.schemas_dir.glob("*_schema.json")):
schema = self.get(path.name.removesuffix("_schema.json"))
if schema:
resources.append(
(
f"./{path.name}",
Resource.from_contents(schema, default_specification=DRAFT7),
)
)
self._registry = Registry().with_resources(resources)
return self._registry

Expand Down
Loading
Loading