From 3fa5a42879f62a388a21ffd795c161c1ef797fb9 Mon Sep 17 00:00:00 2001 From: Frida Rosenaa Date: Mon, 26 Oct 2026 17:37:39 +0100 Subject: [PATCH 1/2] Add sustainability related fields to schema --- docs/manual.md | 80 ++- docs/sustainability-sources.md | 15 + ofd/builder/exporters/api_exporter.py | 50 ++ ofd/builder/exporters/csv_exporter.py | 3 + ofd/builder/exporters/sqlite_exporter.py | 9 +- ofd/commands/build.py | 2 + ofd/scripts/export_data.py | 17 +- ofd/scripts/style_data.py | 72 ++- ofd/validation/data_quality.py | 207 +++++++ reference/README.md | 13 + reference/material_defaults.json | 4 + schemas/filament_schema.json | 5 + schemas/material_defaults_schema.json | 119 +++++ schemas/sizes_schema.json | 89 +++- schemas/sustainability_schema.json | 504 ++++++++++++++++++ schemas/variant_schema.json | 5 + tests/test_api_exporter_endpoints.py | 63 ++- tests/test_data_quality.py | 181 ++++++- tests/test_sustainability_schema.py | 259 +++++++++ .../entity/SustainabilityDisplay.svelte | 163 ++++++ webui/src/lib/components/entity/index.ts | 1 + .../components/form-fields/SizeCard.svelte | 47 +- .../form-fields/SourcedEntryFields.svelte | 105 ++++ .../form-fields/SustainabilityEditor.svelte | 138 +++++ .../__tests__/SustainabilityEditor.test.ts | 43 ++ .../SustainabilityEditorHarness.svelte | 11 + webui/src/lib/components/form-fields/index.ts | 2 + .../lib/components/forms/FilamentForm.svelte | 51 +- .../lib/components/forms/SchemaForm.svelte | 2 + .../lib/components/forms/VariantForm.svelte | 121 ++++- webui/src/lib/server/cloudValidator.ts | 31 +- webui/src/lib/server/schemaHandler.ts | 19 +- webui/src/lib/services/schemaService.ts | 14 +- webui/src/lib/types/changes.ts | 7 +- webui/src/lib/types/database.ts | 86 ++- .../lib/utils/__tests__/dataQuality.test.ts | 93 +++- .../utils/__tests__/sustainability.test.ts | 59 ++ .../lib/utils/__tests__/urlSanitizer.test.ts | 12 + webui/src/lib/utils/dataQuality.ts | 123 ++++- webui/src/lib/utils/sustainability.ts | 138 +++++ webui/src/lib/utils/urlSanitizer.ts | 9 +- webui/src/routes/api/schemas/sizes/+server.ts | 3 + .../api/schemas/sustainability/+server.ts | 3 + .../[material]/[filament]/+page.svelte | 14 +- .../[filament]/[variant]/+page.svelte | 48 +- webui/vitest.config.ts | 4 +- 46 files changed, 2976 insertions(+), 68 deletions(-) create mode 100644 docs/sustainability-sources.md create mode 100644 reference/README.md create mode 100644 reference/material_defaults.json create mode 100644 schemas/material_defaults_schema.json create mode 100644 schemas/sustainability_schema.json create mode 100644 tests/test_sustainability_schema.py create mode 100644 webui/src/lib/components/entity/SustainabilityDisplay.svelte create mode 100644 webui/src/lib/components/form-fields/SourcedEntryFields.svelte create mode 100644 webui/src/lib/components/form-fields/SustainabilityEditor.svelte create mode 100644 webui/src/lib/components/form-fields/__tests__/SustainabilityEditor.test.ts create mode 100644 webui/src/lib/components/form-fields/__tests__/SustainabilityEditorHarness.svelte create mode 100644 webui/src/lib/utils/__tests__/sustainability.test.ts create mode 100644 webui/src/lib/utils/sustainability.ts create mode 100644 webui/src/routes/api/schemas/sizes/+server.ts create mode 100644 webui/src/routes/api/schemas/sustainability/+server.ts diff --git a/docs/manual.md b/docs/manual.md index 30f7883b96..b87f9ca6d4 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -116,6 +116,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. @@ -143,6 +144,7 @@ Inside the filament folder, create a folder named with the variant `id` (e.g. `l - `discontinued` β€” boolean - `hex_variants` β€” array of alternative `#RRGGBB` codes the filament is known to report (e.g. via NFC) - `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 @@ -161,7 +163,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` @@ -170,6 +173,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`. diff --git a/docs/sustainability-sources.md b/docs/sustainability-sources.md new file mode 100644 index 0000000000..b1c4c16028 --- /dev/null +++ b/docs/sustainability-sources.md @@ -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 | +|---|---|---| diff --git a/ofd/builder/exporters/api_exporter.py b/ofd/builder/exporters/api_exporter.py index 7d21e633d0..c1f600e4f1 100644 --- a/ofd/builder/exporters/api_exporter.py +++ b/ofd/builder/exporters/api_exporter.py @@ -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 @@ -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, @@ -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.""" @@ -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) @@ -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, diff --git a/ofd/builder/exporters/csv_exporter.py b/ofd/builder/exporters/csv_exporter.py index 5b7c6a2b0f..065064aed3 100644 --- a/ofd/builder/exporters/csv_exporter.py +++ b/ofd/builder/exporters/csv_exporter.py @@ -48,6 +48,7 @@ "min_print_speed", "max_print_speed", "discontinued", + "sustainability", ], "variant": [ "id", @@ -60,6 +61,7 @@ "color_standards", "traits", "discontinued", + "sustainability", # moved_from is a conditional key that would otherwise sort after color_hexes "moved_from", "color_hexes", @@ -73,6 +75,7 @@ "empty_spool_weight", "spool_core_diameter", "container_material", + "container_details", "gtin", "article_number", "discontinued", diff --git a/ofd/builder/exporters/sqlite_exporter.py b/ofd/builder/exporters/sqlite_exporter.py index 337f0c381d..33f7ba425d 100644 --- a/ofd/builder/exporters/sqlite_exporter.py +++ b/ofd/builder/exporters/sqlite_exporter.py @@ -86,7 +86,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); @@ -104,7 +105,8 @@ hex_variants TEXT, -- JSON array 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); @@ -120,7 +122,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, diff --git a/ofd/commands/build.py b/ofd/commands/build.py index 5724e29cd0..ee47b6e1a3 100644 --- a/ofd/commands/build.py +++ b/ofd/commands/build.py @@ -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 @@ -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") diff --git a/ofd/scripts/export_data.py b/ofd/scripts/export_data.py index 610db87008..86294fc6b0 100644 --- a/ofd/scripts/export_data.py +++ b/ofd/scripts/export_data.py @@ -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 @@ -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 diff --git a/ofd/scripts/style_data.py b/ofd/scripts/style_data.py index 76c165ab17..1d7a4968f3 100644 --- a/ofd/scripts/style_data.py +++ b/ofd/scripts/style_data.py @@ -51,7 +51,7 @@ } # URL fields whose tracking/affiliate query params should be stripped. -URL_FIELDS = {"url", "data_sheet_url", "safety_sheet_url", "storefront_url", "website"} +URL_FIELDS = {"url", "data_sheet_url", "safety_sheet_url", "storefront_url", "website", "source_url"} # Known tracking query-parameter keys (lowercased). Keep in sync with the ofd-validator Rust # rule (crates/ofd-validator-core/src/validators/url_tracker.rs) and the webui urlSanitizer.ts. @@ -246,7 +246,8 @@ def sanitize_data(data: Any, schema_name: str) -> tuple[Any, list[str]]: defined in OPTIONAL_STRING_FIELDS); fix 'id' fields containing hyphens by replacing with underscores. - sizes: default sizes[].diameter from 0 to 1.75; sanitize nested - purchase_links dicts. + purchase_links and container_details dicts. + - filament/variant: sanitize the sourced entries inside ``sustainability``. """ changes: list[str] = [] @@ -262,6 +263,8 @@ def sanitize_data(data: Any, schema_name: str) -> tuple[Any, list[str]]: for j, link in enumerate(size.get("purchase_links", [])): if isinstance(link, dict): _sanitize_dict(link, changes, f"sizes[{i}].purchase_links[{j}]") + if isinstance(size.get("container_details"), dict): + _sanitize_dict(size["container_details"], changes, f"sizes[{i}].container_details") return data, changes if isinstance(data, dict): @@ -274,11 +277,25 @@ def sanitize_data(data: Any, schema_name: str) -> tuple[Any, list[str]]: changes.append(f"id: '{raw_id}' -> '{fixed}'") _sanitize_dict(data, changes) + _sanitize_sustainability(data.get("sustainability"), changes) return data, changes return data, changes +def _sanitize_sustainability(sustainability: Any, changes: list[str]) -> None: + """Sanitize each sourced entry (object or array item) in a sustainability block.""" + if not isinstance(sustainability, dict): + return + for section, value in sustainability.items(): + if isinstance(value, dict): + _sanitize_dict(value, changes, f"sustainability.{section}") + elif isinstance(value, list): + for i, item in enumerate(value): + if isinstance(item, dict): + _sanitize_dict(item, changes, f"sustainability.{section}[{i}]") + + def _sanitize_dict(data: dict[str, Any], changes: list[str], prefix: str = "") -> None: """Sanitize string fields in a dict in-place.""" dot = f"{prefix}." if prefix else "" @@ -387,25 +404,46 @@ def get_property_order(schema: dict[str, Any]) -> list[str]: return [] -def extract_nested_schemas(schema: dict[str, Any]) -> dict[str, list[str]]: - """Recursively extract nested object schemas and their key orderings.""" - nested = {} +def resolve_file_ref(prop_schema: dict[str, Any], schemas: dict[str, dict[str, Any]]) -> dict: + """Resolve a whole-file ``$ref`` such as ``./sustainability_schema.json``.""" + ref = prop_schema.get("$ref", "") + if ref.startswith("./") and ref.endswith(".json") and "#" not in ref: + return schemas.get(Path(ref).stem, prop_schema) + return prop_schema - if "properties" in schema: - for prop_name, prop_schema in schema["properties"].items(): - if isinstance(prop_schema, dict): - if prop_schema.get("type") == "object" and "properties" in prop_schema: + +def extract_nested_schemas( + schema: dict[str, Any], schemas: dict[str, dict[str, Any]] | None = None +) -> dict[str, list[str]]: + """Recursively extract nested object schemas and their key orderings. + + Whole-file ``$ref``s are followed when ``schemas`` is given. The result is a flat + map keyed by property name; the first definition of a name wins. + """ + nested: dict[str, list[str]] = {} + schemas = schemas or {} + + def visit(props: dict[str, Any]) -> None: + for prop_name, prop_schema in props.items(): + if not isinstance(prop_schema, dict): + continue + prop_schema = resolve_file_ref(prop_schema, schemas) + if prop_schema.get("type") == "array" and "items" in prop_schema: + prop_schema = prop_schema["items"] + if not isinstance(prop_schema, dict): + continue + if prop_schema.get("type") == "object" and "properties" in prop_schema: + if prop_name not in nested: nested[prop_name] = get_property_order(prop_schema) - elif prop_schema.get("type") == "array" and "items" in prop_schema: - items_schema = prop_schema["items"] - if isinstance(items_schema, dict) and items_schema.get("type") == "object": - if "properties" in items_schema: - nested[prop_name] = get_property_order(items_schema) + visit(prop_schema["properties"]) + + if "properties" in schema: + visit(schema["properties"]) if "definitions" in schema: for def_name, def_schema in schema["definitions"].items(): if isinstance(def_schema, dict) and def_schema.get("type") == "object": - if "properties" in def_schema: + if "properties" in def_schema and def_name not in nested: nested[def_name] = get_property_order(def_schema) return nested @@ -422,10 +460,10 @@ def build_key_order_map(schemas_dir: Path) -> dict[str, SchemaInfo]: if schema_content.get("type") == "array" and "items" in schema_content: items_schema = schema_content["items"] keys = get_property_order(items_schema) - nested = extract_nested_schemas(items_schema) + nested = extract_nested_schemas(items_schema, schemas) else: keys = get_property_order(schema_content) - nested = extract_nested_schemas(schema_content) + nested = extract_nested_schemas(schema_content, schemas) key_order_map[clean_name] = SchemaInfo(keys=keys, nested=nested) diff --git a/ofd/validation/data_quality.py b/ofd/validation/data_quality.py index 8586e80e71..06f6b511dc 100644 --- a/ofd/validation/data_quality.py +++ b/ofd/validation/data_quality.py @@ -24,6 +24,14 @@ (``name_casing``, ``name_leading_case``, ``fiber_trait_missing``, ``orphan_filament``, ``sibling_near_duplicate``) are WARNINGs. +Sustainability data (``sustainability`` on filaments and variants, +``container_details`` on sizes) must follow "copy, never compute". These are +ERRORs: a missing source field, a percentage outside 0-100, a ``retrieved`` / +``published`` / ``reference_year`` in the future, a number absent from its +``source_quote``, and ``recycled_content.pct > 0`` without ``traits.recycled``. +``traits.recycled`` with no recycled content only WARNs, and only once the filament +or variant has a sustainability block. + A WARNING here is advice, not a failure: ``ofd validate`` still exits 0 and reports "All validations passed (N warnings)". Reviewers should not describe a warning as something that breaks the build or makes data unreachable. @@ -32,6 +40,7 @@ import json import re from collections import Counter, defaultdict +from datetime import date from pathlib import Path from ofd_validator import ValidationError, ValidationLevel @@ -474,6 +483,198 @@ def _check_parent_brands(data_dir: Path, base: Path) -> list[ValidationError]: return errors +# --- Rules: sustainability data ---------------------------------------------- +# +# Sustainability figures follow "copy, never compute": every number is copied from a +# cited source, and the quote must show it. See docs/manual.md#-sustainability-data. + +_SOURCE_FIELDS = ("source_url", "source_quote", "retrieved") + +# Value fields per sourced section; arrays hold one sourced entry per item. +_SUSTAINABILITY_SECTIONS = { + "recycled_content": ("pct",), + "bio_based_content": ("pct",), + "carbon_footprints": ("value_kg_co2e",), + "relative_claims": ("reduction_pct",), +} + +_PCT_FIELDS = {"pct", "recycled_pct", "reduction_pct"} + + +def _sourced_entries(sustainability) -> list[tuple[str, dict, tuple[str, ...]]]: + """(json path, entry, value fields) for every sourced entry in a sustainability block.""" + if not isinstance(sustainability, dict): + return [] + entries = [] + for section, fields in _SUSTAINABILITY_SECTIONS.items(): + value = sustainability.get(section) + if isinstance(value, dict): + entries.append((f"sustainability.{section}", value, fields)) + elif isinstance(value, list): + entries.extend( + (f"sustainability.{section}[{i}]", item, fields) + for i, item in enumerate(value) + if isinstance(item, dict) + ) + return entries + + +def _number_pattern(value) -> re.Pattern: + """Match ``value`` as written in prose: ``5.85`` or ``5,85``, trailing zeros allowed. + + The digit boundaries stop ``5.85`` from matching inside ``15.85`` or ``5.851``. + """ + text = repr(float(value)).rstrip("0").rstrip(".") + int_part, _, frac = text.partition(".") + number = re.escape(int_part) + (f"[.,]{frac}0*" if frac else r"(?:[.,]0+)?") + return re.compile(rf"(? list[ValidationError]: + """One sourced entry: sources present, percentages in range, dates not in the + future, and every number present verbatim in ``source_quote``.""" + from datetime import date + + rel = _rel(file_path, base) + errors: list[ValidationError] = [] + + missing = [f for f in _SOURCE_FIELDS if not str(entry.get(f) or "").strip()] + if missing: + errors.append( + _err( + ValidationLevel.Error, + f"{path} is missing {', '.join(missing)}. Every sustainability figure " + "needs a source URL, a verbatim quote and the date it was retrieved.", + rel, + ) + ) + + for field in value_fields: + value = entry.get(field) + if not isinstance(value, (int, float)) or isinstance(value, bool): + continue + if field in _PCT_FIELDS and not 0 <= value <= 100: + errors.append( + _err( + ValidationLevel.Error, + f"{path}.{field} is {value}; a percentage must be between 0 and 100.", + rel, + ) + ) + quote = entry.get("source_quote") + if isinstance(quote, str) and quote.strip() and not _number_pattern(value).search(quote): + errors.append( + _err( + ValidationLevel.Error, + f"{path}.{field} is {value}, but source_quote does not contain that " + "number. Copy the figure exactly as the source writes it; never " + "derive or convert it.", + rel, + ) + ) + + today = date.today() + for field in ("retrieved", "published"): + raw = entry.get(field) + if raw is None: + continue + parsed = _parse_date(raw) + if parsed is None: + errors.append( + _err( + ValidationLevel.Error, + f"{path}.{field} is {raw!r}; expected a date as YYYY-MM-DD.", + rel, + ) + ) + elif parsed > today: + errors.append( + _err(ValidationLevel.Error, f"{path}.{field} {raw} is in the future.", rel) + ) + + year = entry.get("reference_year") + if isinstance(year, int) and not isinstance(year, bool) and year > today.year: + errors.append( + _err(ValidationLevel.Error, f"{path}.reference_year {year} is in the future.", rel) + ) + + return errors + + +def _check_sustainability(data: dict, file_path: Path, base: Path) -> list[ValidationError]: + """Every sourced entry in a filament's or variant's ``sustainability`` block.""" + errors: list[ValidationError] = [] + for path, entry, fields in _sourced_entries(data.get("sustainability")): + errors.extend(_check_sourced_entry(path, entry, fields, file_path, base)) + return errors + + +def _check_container_details(sizes, file_path: Path, base: Path) -> list[ValidationError]: + """``container_details`` on each size is a sourced entry like the ones above.""" + if not isinstance(sizes, list): + return [] + errors: list[ValidationError] = [] + for i, size in enumerate(sizes): + details = size.get("container_details") if isinstance(size, dict) else None + if isinstance(details, dict): + errors.extend( + _check_sourced_entry( + f"[{i}].container_details", details, ("recycled_pct",), file_path, base + ) + ) + return errors + + +def _check_recycled_trait( + filament_data: dict, variant_data: dict, file_path: Path, base: Path +) -> list[ValidationError]: + """``recycled_content`` and ``traits.recycled`` must agree on each variant. + + A variant's ``sustainability`` overrides the filament's per field, so the effective + ``recycled_content`` is the variant's if it sets one, otherwise the filament's. + A positive percentage without the trait is an ERROR. The trait without any recycled + content only WARNs, and only once a sustainability block exists on the filament or + variant: until a brand has been researched, the trait alone is expected. + """ + filament_sus = filament_data.get("sustainability") + variant_sus = variant_data.get("sustainability") + filament_sus = filament_sus if isinstance(filament_sus, dict) else {} + variant_sus = variant_sus if isinstance(variant_sus, dict) else {} + + content = variant_sus.get("recycled_content", filament_sus.get("recycled_content")) + pct = content.get("pct") if isinstance(content, dict) else None + traits = variant_data.get("traits") + has_trait = isinstance(traits, dict) and traits.get("recycled") is True + + if isinstance(pct, (int, float)) and pct > 0 and not has_trait: + return [ + _err( + ValidationLevel.Error, + f"recycled_content.pct is {pct} but traits.recycled is not set on this variant.", + _rel(file_path, base), + ) + ] + if has_trait and (filament_sus or variant_sus) and (content is None or pct == 0): + return [ + _err( + ValidationLevel.Warning, + "traits.recycled is set and sustainability data exists, but there is no " + "recycled_content for this variant.", + _rel(file_path, base), + ) + ] + return [] + + # --- Entry point -------------------------------------------------------------- @@ -515,6 +716,7 @@ def check_data_quality(data_dir) -> list[ValidationError]: errors.extend(_check_name_whitespace(filament_data, filament_file, base)) errors.extend(_check_name_leading_case(filament_data, filament_file, base)) errors.extend(_check_orphan_filament(filament_dir, base)) + errors.extend(_check_sustainability(filament_data, filament_file, base)) name = filament_data.get("name") if isinstance(name, str) and name: @@ -548,6 +750,10 @@ def check_data_quality(data_dir) -> list[ValidationError]: if part ) errors.extend(_check_fiber_traits(variant_data, fiber_text, variant_file, base)) + errors.extend(_check_sustainability(variant_data, variant_file, base)) + errors.extend( + _check_recycled_trait(filament_data, variant_data, variant_file, base) + ) variant_name = variant_data.get("name") if isinstance(variant_name, str) and variant_name: @@ -559,6 +765,7 @@ def check_data_quality(data_dir) -> list[ValidationError]: sizes = _load_json(sizes_file) errors.extend(_check_placeholders(sizes, sizes_file, base)) errors.extend(_check_duplicate_sizes(sizes, sizes_file, base)) + errors.extend(_check_container_details(sizes, sizes_file, base)) errors.extend(_check_sibling_casing(variant_names, base)) errors.extend(_check_sibling_duplicates(variant_ids, base)) diff --git a/reference/README.md b/reference/README.md new file mode 100644 index 0000000000..8cac1e05b0 --- /dev/null +++ b/reference/README.md @@ -0,0 +1,13 @@ +# Reference data + +Data that is **not** manufacturer data, so it is kept outside `data/`. The crawler, the UUID tooling and the data-quality checks never read this folder. + +## `material_defaults.json` + +Generic per-material carbon estimates (kg COβ‚‚e per kg, virgin and recycled), keyed on the material types in [`schemas/material_types_schema.json`](../schemas/material_types_schema.json). Tools can use these as a fallback when a brand publishes no figure of its own. + +- Validated against [`schemas/material_defaults_schema.json`](../schemas/material_defaults_schema.json) during `ofd build`. An invalid file fails the build. +- Published as `api/v1/material-defaults.json`. The API index lists it only when the file exists. +- Every entry is `"kind": "estimate"` and needs `sources`. + +It ships with `entries: []` on purpose. The values will be supplied separately (possibly from a commissioned LCA). **Do not fill it from a single brand's figure.** Brand figures belong in that brand's `sustainability` data, and a default built from one brand would misrepresent every other. diff --git a/reference/material_defaults.json b/reference/material_defaults.json new file mode 100644 index 0000000000..925fc770cd --- /dev/null +++ b/reference/material_defaults.json @@ -0,0 +1,4 @@ +{ + "version": 1, + "entries": [] +} diff --git a/schemas/filament_schema.json b/schemas/filament_schema.json index 3f77050ccd..190e17e067 100644 --- a/schemas/filament_schema.json +++ b/schemas/filament_schema.json @@ -269,6 +269,11 @@ "title": "Discontinued", "description": "Mark if this filament has been discontinued by the manufacturer" }, + "sustainability": { + "$ref": "./sustainability_schema.json", + "title": "Sustainability", + "description": "Sourced sustainability data (recycled and bio-based content, carbon footprints, relative claims). Every number must be copied verbatim from a cited source." + }, "slicer_ids": { "type": "object", "title": "Slicer IDs", diff --git a/schemas/material_defaults_schema.json b/schemas/material_defaults_schema.json new file mode 100644 index 0000000000..3abcc34789 --- /dev/null +++ b/schemas/material_defaults_schema.json @@ -0,0 +1,119 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "title": "Material Defaults", + "description": "Generic per-material carbon estimates. These are estimates, not manufacturer data, and are kept outside data/.", + "type": "object", + "properties": { + "version": { + "type": "integer", + "minimum": 1 + }, + "entries": { + "type": "array", + "items": { + "type": "object", + "properties": { + "material": { + "$ref": "./material_types_schema.json" + }, + "virgin_kg_co2e_per_kg": { + "type": [ + "number", + "null" + ], + "minimum": 0 + }, + "recycled_kg_co2e_per_kg": { + "type": [ + "number", + "null" + ], + "minimum": 0 + }, + "boundary": { + "type": "string", + "title": "System Boundary", + "description": "Life-cycle stages covered: resin production only, filament up to the factory gate, delivery to the customer, or the full life cycle", + "enum": [ + "resin_cradle_to_gate", + "filament_cradle_to_gate", + "cradle_to_customer", + "cradle_to_grave", + "unknown" + ] + }, + "packaging_included": { + "type": "string", + "title": "Packaging Included", + "description": "Whether spool and packaging are inside the figure", + "enum": [ + "yes", + "no", + "unknown" + ] + }, + "sources": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "url": { + "type": "string", + "title": "Source URL", + "description": "Where the figure is published", + "format": "uri", + "pattern": "^https?://", + "maxLength": 1000, + "x-placeholder": "https://example.com/..." + }, + "quote": { + "type": "string", + "title": "Source Quote", + "description": "Verbatim text from the source. Must contain the number exactly as written.", + "minLength": 1, + "maxLength": 2000 + }, + "retrieved": { + "type": "string", + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "title": "Retrieved", + "description": "Date the source was read (YYYY-MM-DD)" + } + }, + "additionalProperties": false, + "required": [ + "url", + "retrieved" + ] + } + }, + "kind": { + "const": "estimate" + }, + "version": { + "type": "integer", + "minimum": 1 + } + }, + "additionalProperties": false, + "required": [ + "material", + "virgin_kg_co2e_per_kg", + "recycled_kg_co2e_per_kg", + "boundary", + "packaging_included", + "sources", + "kind", + "version" + ] + } + } + }, + "additionalProperties": false, + "required": [ + "version", + "entries" + ] +} \ No newline at end of file diff --git a/schemas/sizes_schema.json b/schemas/sizes_schema.json index aea01267ad..17f279ec6f 100644 --- a/schemas/sizes_schema.json +++ b/schemas/sizes_schema.json @@ -43,13 +43,100 @@ }, "container_material": { "type": "string", - "description": "The material the filament container is made of, or refill for a spool-less refill", + "description": "The material the filament container is made of (mixed = more than one, e.g. cardboard core with plastic sides), or refill for a spool-less refill", "enum": [ "plastic", "cardboard", + "mixed", "refill" ] }, + "container_details": { + "type": "object", + "title": "Container Details", + "description": "Sourced details about the spool or container of this size", + "properties": { + "recycled_pct": { + "type": [ + "number", + "null" + ], + "minimum": 0, + "maximum": 100, + "title": "Recycled %", + "description": "Recycled content of the container in percent (0-100). null when the source gives no number." + }, + "pct_qualifier": { + "type": "string", + "title": "Percentage Qualifier", + "description": "How the source qualifies the percentage: exact, up to, or at least", + "enum": [ + "exact", + "up_to", + "at_least" + ], + "default": "exact" + }, + "certifications": { + "type": "array", + "title": "Certifications", + "description": "Certifications of the container material, e.g. FSC", + "items": { + "type": "string", + "maxLength": 100 + }, + "uniqueItems": true + }, + "notes": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Notes", + "description": "Caveats, conflicting sources, or anything a reader needs to interpret the value" + }, + "source_type": { + "type": "string", + "title": "Source Type", + "description": "primary = the brand's own site, PDF, blog or declaration. secondary = a retailer or press copy of brand text, only when the original can't be reached.", + "enum": [ + "primary", + "secondary" + ] + }, + "source_url": { + "type": "string", + "title": "Source URL", + "description": "Where the figure is published", + "format": "uri", + "pattern": "^https?://", + "maxLength": 1000, + "x-placeholder": "https://example.com/..." + }, + "source_quote": { + "type": "string", + "title": "Source Quote", + "description": "Verbatim text from the source. Must contain the number exactly as written.", + "minLength": 1, + "maxLength": 2000 + }, + "retrieved": { + "type": "string", + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "title": "Retrieved", + "description": "Date the source was read (YYYY-MM-DD)" + } + }, + "additionalProperties": false, + "required": [ + "source_type", + "source_url", + "source_quote", + "retrieved" + ] + }, "empty_spool_weight": { "type": "number", "description": "The weight of a spool with no filament (in grams)" diff --git a/schemas/sustainability_schema.json b/schemas/sustainability_schema.json new file mode 100644 index 0000000000..ed87b227f4 --- /dev/null +++ b/schemas/sustainability_schema.json @@ -0,0 +1,504 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "./sustainability_schema.json", + "title": "Sustainability", + "description": "Sourced sustainability data. Copy, never compute: every number must appear verbatim in source_quote. On a variant, each field set here replaces the filament's field of the same name (carbon_footprints and relative_claims replace the whole array).", + "type": "object", + "properties": { + "recycled_content": { + "type": "object", + "title": "Recycled Content", + "description": "Share of recycled material in the filament, as declared by the brand", + "properties": { + "pct": { + "type": [ + "number", + "null" + ], + "minimum": 0, + "maximum": 100, + "title": "Recycled %", + "description": "Recycled content in percent (0-100). null when the source gives no number." + }, + "pct_qualifier": { + "type": "string", + "title": "Percentage Qualifier", + "description": "How the source qualifies the percentage: exact, up to, or at least", + "enum": [ + "exact", + "up_to", + "at_least" + ], + "default": "exact" + }, + "type": { + "type": "string", + "title": "Recycled Material Type", + "description": "Origin of the recycled material, as stated by the source", + "enum": [ + "post_industrial", + "post_consumer", + "mixed", + "unknown" + ] + }, + "evidence": { + "type": "string", + "title": "Evidence", + "description": "What backs the figure: an ISO 14021 self-declaration, a third-party certificate (GRS, RCS, SCS...), a supplier declaration, or marketing text", + "enum": [ + "iso_14021", + "third_party_certified", + "supplier_declaration", + "marketing" + ] + }, + "source_type": { + "type": "string", + "title": "Source Type", + "description": "primary = the brand's own site, PDF, blog or declaration. secondary = a retailer or press copy of brand text, only when the original can't be reached.", + "enum": [ + "primary", + "secondary" + ] + }, + "source_url": { + "type": "string", + "title": "Source URL", + "description": "Where the figure is published", + "format": "uri", + "pattern": "^https?://", + "maxLength": 1000, + "x-placeholder": "https://example.com/..." + }, + "source_quote": { + "type": "string", + "title": "Source Quote", + "description": "Verbatim text from the source. Must contain the number exactly as written.", + "minLength": 1, + "maxLength": 2000 + }, + "retrieved": { + "type": "string", + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "title": "Retrieved", + "description": "Date the source was read (YYYY-MM-DD)" + }, + "notes": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Notes", + "description": "Caveats, conflicting sources, or anything a reader needs to interpret the value" + } + }, + "additionalProperties": false, + "required": [ + "pct", + "type", + "evidence", + "source_type", + "source_url", + "source_quote", + "retrieved" + ] + }, + "bio_based_content": { + "type": "object", + "title": "Bio-based Content", + "description": "Share of bio-based carbon or material in the filament. Bio-based pigments or additives are not bio-based content.", + "properties": { + "pct": { + "type": [ + "number", + "null" + ], + "minimum": 0, + "maximum": 100, + "title": "Bio-based %", + "description": "Bio-based content in percent (0-100). null when the source gives no number." + }, + "pct_qualifier": { + "type": "string", + "title": "Percentage Qualifier", + "description": "How the source qualifies the percentage: exact, up to, or at least", + "enum": [ + "exact", + "up_to", + "at_least" + ], + "default": "exact" + }, + "method": { + "type": "string", + "title": "Method", + "description": "How the bio-based share was determined", + "enum": [ + "astm_d6866", + "en_16785", + "declared" + ] + }, + "source_type": { + "type": "string", + "title": "Source Type", + "description": "primary = the brand's own site, PDF, blog or declaration. secondary = a retailer or press copy of brand text, only when the original can't be reached.", + "enum": [ + "primary", + "secondary" + ] + }, + "source_url": { + "type": "string", + "title": "Source URL", + "description": "Where the figure is published", + "format": "uri", + "pattern": "^https?://", + "maxLength": 1000, + "x-placeholder": "https://example.com/..." + }, + "source_quote": { + "type": "string", + "title": "Source Quote", + "description": "Verbatim text from the source. Must contain the number exactly as written.", + "minLength": 1, + "maxLength": 2000 + }, + "retrieved": { + "type": "string", + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "title": "Retrieved", + "description": "Date the source was read (YYYY-MM-DD)" + }, + "notes": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Notes", + "description": "Caveats, conflicting sources, or anything a reader needs to interpret the value" + } + }, + "additionalProperties": false, + "required": [ + "pct", + "method", + "source_type", + "source_url", + "source_quote", + "retrieved" + ] + }, + "carbon_footprints": { + "type": "array", + "title": "Carbon Footprints", + "items": { + "type": "object", + "title": "Carbon Footprint", + "description": "A published carbon footprint figure, copied verbatim from the source", + "properties": { + "value_kg_co2e": { + "type": "number", + "minimum": 0, + "title": "kg CO2e", + "description": "Footprint in kg CO2e, exactly as published" + }, + "declared_unit": { + "type": "string", + "title": "Declared Unit", + "description": "What the value refers to. unknown when the source does not say.", + "enum": [ + "per_kg_filament", + "per_spool_as_sold", + "unknown" + ] + }, + "boundary": { + "type": "string", + "title": "System Boundary", + "description": "Life-cycle stages covered: resin production only, filament up to the factory gate, delivery to the customer, or the full life cycle", + "enum": [ + "resin_cradle_to_gate", + "filament_cradle_to_gate", + "cradle_to_customer", + "cradle_to_grave", + "unknown" + ] + }, + "packaging_included": { + "type": "string", + "title": "Packaging Included", + "description": "Whether spool and packaging are inside the figure", + "enum": [ + "yes", + "no", + "unknown" + ] + }, + "biogenic_carbon": { + "type": "string", + "title": "Biogenic Carbon", + "description": "How biogenic carbon uptake is treated", + "enum": [ + "included", + "excluded", + "reported_separately", + "unknown" + ] + }, + "recycled_allocation": { + "type": "string", + "title": "Recycled Allocation", + "description": "How the burden of recycled input is allocated. not_applicable for virgin material.", + "enum": [ + "cut_off", + "burden_free_scrap", + "other", + "unknown", + "not_applicable" + ] + }, + "method": { + "type": "string", + "title": "Method", + "description": "epd = registered EPD, iso_14067 = product carbon footprint to ISO 14067, lca = other life-cycle assessment, declaration = a figure with no published study", + "enum": [ + "epd", + "iso_14067", + "lca", + "declaration" + ] + }, + "standard": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Standard", + "description": "Standard named by the source, e.g. ISO 14067. Only if the source names one." + }, + "tool": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Tool", + "description": "LCA software as named by the source, e.g. SimaPro 9.3.0.2" + }, + "practitioner": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Practitioner", + "description": "Person or firm that performed the study" + }, + "verification": { + "type": "string", + "title": "Verification", + "description": "Independent review of the study", + "enum": [ + "none", + "peer_review", + "third_party", + "epd_registered" + ] + }, + "verifier": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Verifier" + }, + "epd_registration_number": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "EPD Registration Number" + }, + "publicly_available": { + "type": "boolean", + "title": "Study Publicly Available", + "description": "false when the underlying study is only available on request" + }, + "reference_year": { + "type": [ + "integer", + "null" + ], + "minimum": 1990, + "title": "Reference Year", + "description": "Year the data refers to" + }, + "published": { + "type": [ + "string", + "null" + ], + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "title": "Published", + "description": "Publication date of the source (YYYY-MM-DD)" + }, + "source_type": { + "type": "string", + "title": "Source Type", + "description": "primary = the brand's own site, PDF, blog or declaration. secondary = a retailer or press copy of brand text, only when the original can't be reached.", + "enum": [ + "primary", + "secondary" + ] + }, + "source_url": { + "type": "string", + "title": "Source URL", + "description": "Where the figure is published", + "format": "uri", + "pattern": "^https?://", + "maxLength": 1000, + "x-placeholder": "https://example.com/..." + }, + "source_quote": { + "type": "string", + "title": "Source Quote", + "description": "Verbatim text from the source. Must contain the number exactly as written.", + "minLength": 1, + "maxLength": 2000 + }, + "retrieved": { + "type": "string", + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "title": "Retrieved", + "description": "Date the source was read (YYYY-MM-DD)" + }, + "notes": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Notes", + "description": "Caveats, conflicting sources, or anything a reader needs to interpret the value" + } + }, + "additionalProperties": false, + "required": [ + "value_kg_co2e", + "declared_unit", + "boundary", + "packaging_included", + "biogenic_carbon", + "recycled_allocation", + "method", + "verification", + "publicly_available", + "source_type", + "source_url", + "source_quote", + "retrieved" + ] + }, + "minItems": 1 + }, + "relative_claims": { + "type": "array", + "title": "Relative Claims", + "items": { + "type": "object", + "title": "Relative Claim", + "description": "A published reduction relative to a baseline, for brands that publish no absolute figure", + "properties": { + "reduction_pct": { + "type": "number", + "minimum": 0, + "maximum": 100, + "title": "Reduction %", + "description": "Reduction in percent, exactly as published" + }, + "metric": { + "type": "string", + "title": "Metric", + "description": "gwp = global warming potential (CO2e)", + "enum": [ + "gwp", + "other" + ] + }, + "baseline": { + "type": "string", + "minLength": 1, + "maxLength": 1000, + "title": "Baseline", + "description": "What the reduction is relative to, verbatim from the source" + }, + "source_type": { + "type": "string", + "title": "Source Type", + "description": "primary = the brand's own site, PDF, blog or declaration. secondary = a retailer or press copy of brand text, only when the original can't be reached.", + "enum": [ + "primary", + "secondary" + ] + }, + "source_url": { + "type": "string", + "title": "Source URL", + "description": "Where the figure is published", + "format": "uri", + "pattern": "^https?://", + "maxLength": 1000, + "x-placeholder": "https://example.com/..." + }, + "source_quote": { + "type": "string", + "title": "Source Quote", + "description": "Verbatim text from the source. Must contain the number exactly as written.", + "minLength": 1, + "maxLength": 2000 + }, + "retrieved": { + "type": "string", + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "title": "Retrieved", + "description": "Date the source was read (YYYY-MM-DD)" + }, + "notes": { + "type": [ + "string", + "null" + ], + "maxLength": 1000, + "title": "Notes", + "description": "Caveats, conflicting sources, or anything a reader needs to interpret the value" + } + }, + "additionalProperties": false, + "required": [ + "reduction_pct", + "metric", + "baseline", + "source_type", + "source_url", + "source_quote", + "retrieved" + ] + }, + "minItems": 1 + } + }, + "additionalProperties": false +} \ No newline at end of file diff --git a/schemas/variant_schema.json b/schemas/variant_schema.json index aec9d45ebc..57c190ee25 100644 --- a/schemas/variant_schema.json +++ b/schemas/variant_schema.json @@ -79,6 +79,11 @@ "title": "Discontinued", "description": "Mark if this color variant has been discontinued" }, + "sustainability": { + "$ref": "./sustainability_schema.json", + "title": "Sustainability", + "description": "Overrides the filament's sustainability data per field: each field set here replaces the filament's field of the same name (carbon_footprints and relative_claims replace the whole array)." + }, "color_standards": { "type": "object", "properties": { diff --git a/tests/test_api_exporter_endpoints.py b/tests/test_api_exporter_endpoints.py index 286a6f82a0..fd742420e7 100644 --- a/tests/test_api_exporter_endpoints.py +++ b/tests/test_api_exporter_endpoints.py @@ -6,6 +6,11 @@ """ import json +import shutil +from pathlib import Path + +import jsonschema +import pytest from ofd.builder.exporters import export_api from ofd.builder.models import Database @@ -27,7 +32,7 @@ def read_index(out_dir): return json.loads((out_dir / "api" / "v1" / "index.json").read_text(encoding="utf-8")) -def export(tmp_path, schemas_dir=None): +def export(tmp_path, schemas_dir=None, reference_dir=None): out = tmp_path / "dist" export_api( make_db(), @@ -37,6 +42,7 @@ def export(tmp_path, schemas_dir=None): schemas_dir=str(schemas_dir) if schemas_dir else None, data_dir=str(tmp_path / "data"), stores_dir=str(tmp_path / "stores"), + reference_dir=str(reference_dir) if reference_dir else None, ) return out @@ -82,3 +88,58 @@ def test_every_advertised_relative_endpoint_resolves(tmp_path): if target.startswith("../") or target.endswith("/"): continue assert (api_v1 / target).exists(), f"endpoint {name!r} points at a missing {target}" + + +REPO_SCHEMAS = Path(__file__).resolve().parent.parent / "schemas" + + +def reference_with(tmp_path, defaults): + reference = tmp_path / "reference" + reference.mkdir() + (reference / "material_defaults.json").write_text(json.dumps(defaults), encoding="utf-8") + return reference + + +def test_material_defaults_endpoint_is_advertised_when_written(tmp_path): + schemas = tmp_path / "schemas" + shutil.copytree(REPO_SCHEMAS, schemas) + reference = reference_with(tmp_path, {"version": 1, "entries": []}) + + out = export(tmp_path, schemas, reference) + endpoints = read_index(out)["endpoints"] + + assert endpoints["material_defaults"] == "material-defaults.json" + published = json.loads((out / "api" / "v1" / "material-defaults.json").read_text("utf-8")) + assert published == {"version": 1, "entries": []} + + +def test_material_defaults_endpoint_is_absent_without_the_file(tmp_path): + schemas = tmp_path / "schemas" + shutil.copytree(REPO_SCHEMAS, schemas) + (tmp_path / "reference").mkdir() + + endpoints = read_index(export(tmp_path, schemas, tmp_path / "reference"))["endpoints"] + assert "material_defaults" not in endpoints + + +def test_invalid_material_defaults_fail_the_build(tmp_path): + schemas = tmp_path / "schemas" + shutil.copytree(REPO_SCHEMAS, schemas) + # An estimate must say it is one. + bad = { + "version": 1, + "entries": [ + { + "material": "PLA", + "virgin_kg_co2e_per_kg": 2.0, + "recycled_kg_co2e_per_kg": None, + "boundary": "resin_cradle_to_gate", + "packaging_included": "no", + "sources": [{"url": "https://example.com/", "retrieved": "2026-10-01"}], + "kind": "manufacturer", + "version": 1, + } + ], + } + with pytest.raises(jsonschema.ValidationError): + export(tmp_path, schemas, reference_with(tmp_path, bad)) diff --git a/tests/test_data_quality.py b/tests/test_data_quality.py index 8ab39ea46a..f8214c0290 100644 --- a/tests/test_data_quality.py +++ b/tests/test_data_quality.py @@ -25,7 +25,7 @@ def build( ): """Lay out data/////{variant,sizes}.json. - `variants` items are dicts: {id, name?, traits?, sizes?}. + `variants` items are dicts: {id, name?, traits?, sustainability?, sizes?}. """ fil_dir = data_dir / brand / material / filament write(data_dir / brand / "brand.json", {"id": brand, "name": brand.title()}) @@ -44,6 +44,8 @@ def build( } if "traits" in v: variant_obj["traits"] = v["traits"] + if "sustainability" in v: + variant_obj["sustainability"] = v["sustainability"] write(vdir / "variant.json", variant_obj) write( vdir / "sizes.json", @@ -575,3 +577,180 @@ def test_parent_brand_cannot_be_itself_or_a_cycle(tmp_path): "parent_brand forms a cycle through 'b'", "parent_brand names the brand itself", ] + + +# --- Sustainability data -------------------------------------------------------- +# +# The sourcing rules from the sustainability brief: copy, never compute. + +SOURCE = { + "source_type": "primary", + "source_url": "https://blog.prusa3d.com/introducing-prusament-petg-recycled/", + "retrieved": "2026-10-21", +} + + +def footprint(value, quote, **extra): + return { + "value_kg_co2e": value, + "declared_unit": "per_kg_filament", + "boundary": "filament_cradle_to_gate", + "packaging_included": "unknown", + "biogenic_carbon": "unknown", + "recycled_allocation": "not_applicable", + "method": "lca", + "verification": "none", + "publicly_available": True, + **SOURCE, + "source_quote": quote, + **extra, + } + + +def recycled(pct, quote="made from 100% recycled material", **extra): + return { + "pct": pct, + "type": "post_industrial", + "evidence": "supplier_declaration", + **SOURCE, + "source_quote": quote, + **extra, + } + + +def sustainability_errors(tmp_path, *, filament=None, variant=None, traits=None, sizes=None): + v = {"id": "black", "name": "Black"} + if variant is not None: + v["sustainability"] = variant + if traits is not None: + v["traits"] = traits + if sizes is not None: + v["sizes"] = sizes + extra = {"sustainability": filament} if filament is not None else None + data = build(tmp_path / "data", filament_extra=extra, variants=[v]) + return check_data_quality(data) + + +def test_sourced_footprint_passes(tmp_path): + quote = "The results show 5.85 kg of CO2 with 1kg of pure Prusament PETG" + errors = sustainability_errors( + tmp_path, filament={"carbon_footprints": [footprint(5.85, quote)]} + ) + assert errors == [] + + +def test_quote_with_decimal_comma_passes(tmp_path): + errors = sustainability_errors( + tmp_path, filament={"carbon_footprints": [footprint(5.85, "5,85 kg CO2e")]} + ) + assert messages(errors, "does not contain that number") == [] + + +def test_quote_missing_the_number_is_an_error(tmp_path): + errors = sustainability_errors( + tmp_path, filament={"carbon_footprints": [footprint(5.85, "about six kilograms")]} + ) + found = messages(errors, "does not contain that number") + assert len(found) == 1 + assert found[0].level.value == "ERROR" + + +def test_number_inside_a_longer_number_does_not_count(tmp_path): + errors = sustainability_errors( + tmp_path, filament={"carbon_footprints": [footprint(5.85, "15.85 kg of CO2")]} + ) + assert len(messages(errors, "does not contain that number")) == 1 + + +def test_missing_source_fields_are_an_error(tmp_path): + entry = footprint(5.85, "5.85 kg") + del entry["source_url"] + entry["retrieved"] = "" + errors = sustainability_errors(tmp_path, filament={"carbon_footprints": [entry]}) + found = messages(errors, "is missing source_url, retrieved") + assert len(found) == 1 + assert found[0].level.value == "ERROR" + + +def test_future_dates_are_an_error(tmp_path): + entry = footprint(5.85, "5.85 kg", published="2999-01-01", reference_year=2999) + entry["retrieved"] = "2999-01-02" + errors = sustainability_errors(tmp_path, filament={"carbon_footprints": [entry]}) + assert len(messages(errors, "is in the future")) == 3 + + +def test_pct_out_of_range_is_an_error(tmp_path): + errors = sustainability_errors( + tmp_path, + filament={"recycled_content": recycled(120, "120% recycled")}, + traits={"recycled": True}, + ) + assert len(messages(errors, "between 0 and 100")) == 1 + + +def test_recycled_pct_without_trait_is_an_error(tmp_path): + errors = sustainability_errors(tmp_path, filament={"recycled_content": recycled(100)}) + found = messages(errors, "traits.recycled is not set") + assert len(found) == 1 + assert found[0].level.value == "ERROR" + + +def test_recycled_pct_with_trait_passes(tmp_path): + errors = sustainability_errors( + tmp_path, filament={"recycled_content": recycled(100)}, traits={"recycled": True} + ) + assert errors == [] + + +def test_unknown_recycled_pct_does_not_require_trait(tmp_path): + errors = sustainability_errors( + tmp_path, filament={"recycled_content": recycled(None, "made from recycled scrap")} + ) + assert messages(errors, "traits.recycled") == [] + + +def test_variant_override_replaces_filament_recycled_content(tmp_path): + # The filament says 100% recycled, but this variant overrides it with 0%, + # so the variant needs no trait for the forward rule. + errors = sustainability_errors( + tmp_path, + filament={"recycled_content": recycled(100)}, + variant={"recycled_content": recycled(0, "contains 0% recycled material")}, + ) + assert messages(errors, "traits.recycled is not set") == [] + + +def test_trait_without_any_sustainability_block_is_silent(tmp_path): + # 265 variants carry the trait before any brand has been researched. + errors = sustainability_errors(tmp_path, traits={"recycled": True}) + assert messages(errors, "no recycled_content") == [] + + +def test_trait_without_recycled_content_warns_once_block_exists(tmp_path): + errors = sustainability_errors( + tmp_path, + filament={"carbon_footprints": [footprint(2.55, "only 2.55 kg CO2 emissions")]}, + traits={"recycled": True}, + ) + found = messages(errors, "no recycled_content") + assert len(found) == 1 + assert found[0].level.value == "WARNING" + + +def test_container_details_are_checked(tmp_path): + sizes = [ + { + "filament_weight": 1000, + "diameter": 1.75, + "container_material": "mixed", + "container_details": { + "recycled_pct": 90, + "pct_qualifier": "at_least", + **SOURCE, + "source_quote": "spools are based on 80 - 100% recycled raw material", + }, + } + ] + errors = sustainability_errors(tmp_path, sizes=sizes) + found = messages(errors, "container_details.recycled_pct is 90") + assert len(found) == 1 diff --git a/tests/test_sustainability_schema.py b/tests/test_sustainability_schema.py new file mode 100644 index 0000000000..cfcd861dbd --- /dev/null +++ b/tests/test_sustainability_schema.py @@ -0,0 +1,259 @@ +"""Sustainability schema, its cross-file $ref, and how the exporters carry it. + +`sustainability` lives in schemas/sustainability_schema.json and is pulled into the +filament and variant schemas with a cross-file `$ref`, so every validator that reads +the schemas must resolve that reference. +""" + +import csv +import json +import shutil +import sqlite3 +from pathlib import Path + +import ofd_validator +import pytest +from jsonschema import Draft7Validator + +from ofd.builder.exporters import export_csv, export_sqlite +from ofd.builder.models import Database +from ofd.scripts.export_data import SchemaLoader + +ROOT = Path(__file__).resolve().parent.parent +SCHEMAS = ROOT / "schemas" + +SOURCE = { + "source_type": "primary", + "source_url": "https://blog.prusa3d.com/introducing-prusament-petg-recycled-with-calculated-life-cycle-assessment_65806/", + "retrieved": "2026-10-21", +} + +PETG_FOOTPRINT = { + "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", + "standard": None, + "tool": "SimaPro 9.3.0.2", + "practitioner": "Ing. Marie TichΓ‘", + "verification": "none", + "verifier": None, + "epd_registration_number": None, + "publicly_available": True, + "reference_year": 2022, + "published": "2022-03-17", + **SOURCE, + "source_quote": "The results show 5.85 kg of CO2 with 1kg of pure Prusament PETG", + "notes": None, +} + +CONTAINER_DETAILS = { + "recycled_pct": 100, + "pct_qualifier": "exact", + "certifications": ["FSC"], + **SOURCE, + "source_quote": "spool sides from a 100% recycled polycarbonate", +} + + +def validator(name): + loader = SchemaLoader(SCHEMAS) + return Draft7Validator(loader.get(name), registry=loader.registry) + + +def filament(**sustainability): + return { + "id": "petg", + "name": "PETG", + "density": 1.27, + "diameter_tolerance": 0.02, + "sustainability": sustainability, + } + + +def error_messages(name, doc): + return [e.message for e in validator(name).iter_errors(doc)] + + +def test_full_prusament_style_entry_is_valid(): + assert error_messages("filament", filament(carbon_footprints=[PETG_FOOTPRINT])) == [] + + +def test_variant_accepts_sustainability_override(): + variant = { + "id": "recycled", + "name": "Recycled", + "color_hex": "#556D5A", + "traits": {"recycled": True}, + "sustainability": { + "recycled_content": { + "pct": 100, + "pct_qualifier": "exact", + "type": "post_industrial", + "evidence": "supplier_declaration", + **SOURCE, + "source_quote": "Crafted from 100% recycled Prusament materials", + } + }, + } + assert error_messages("variant", variant) == [] + + +def test_unknown_enum_value_is_rejected(): + entry = {**PETG_FOOTPRINT, "boundary": "gate_to_moon"} + assert error_messages("filament", filament(carbon_footprints=[entry])) + + +def test_unknown_key_is_rejected(): + # Offsets are never stored; the schema has nowhere to put them. + entry = {**PETG_FOOTPRINT, "offset_trees": 5} + assert error_messages("filament", filament(carbon_footprints=[entry])) + + +def test_missing_source_is_rejected(): + entry = {k: v for k, v in PETG_FOOTPRINT.items() if k != "source_quote"} + assert error_messages("filament", filament(carbon_footprints=[entry])) + + +def test_null_pct_is_allowed_when_the_source_gives_no_number(): + content = { + "pct": None, + "type": "post_industrial", + "evidence": "marketing", + **SOURCE, + "source_quote": "semi-finished filaments not produced as planned during manufacturing", + } + assert error_messages("filament", filament(recycled_content=content)) == [] + + +def test_sizes_accept_mixed_container_and_details(): + sizes = [ + { + "filament_weight": 1000, + "diameter": 1.75, + "container_material": "mixed", + "container_details": CONTAINER_DETAILS, + } + ] + assert error_messages("sizes", sizes) == [] + + +def test_material_defaults_scaffold_is_valid(): + doc = json.loads((ROOT / "reference" / "material_defaults.json").read_text(encoding="utf-8")) + assert doc["entries"] == [] + assert error_messages("material_defaults", doc) == [] + + +def test_ofd_validator_resolves_the_cross_file_ref(tmp_path): + """The Rust validator must find sustainability_schema.json for the `$ref`.""" + src = ROOT / "data" / "prusament" + if not (src / "PETG" / "petg").exists(): + pytest.skip("prusament PETG not in data/") + data = tmp_path / "data" / "prusament" + data.mkdir(parents=True) + for f in src.iterdir(): + if f.is_file(): + shutil.copy2(f, data / f.name) + (data / "PETG").mkdir() + shutil.copy2(src / "PETG" / "material.json", data / "PETG" / "material.json") + shutil.copytree(src / "PETG" / "petg", data / "PETG" / "petg") + + fil = data / "PETG" / "petg" / "filament.json" + doc = json.loads(fil.read_text(encoding="utf-8")) + doc["sustainability"] = {"carbon_footprints": [PETG_FOOTPRINT]} + fil.write_text(json.dumps(doc), encoding="utf-8") + + def schema_errors(): + result = ofd_validator.validate_json_files( + str(tmp_path / "data"), str(ROOT / "stores"), str(SCHEMAS) + ) + return [e.message for e in result.errors if "chema" in e.message] + + assert schema_errors() == [] + + doc["sustainability"]["carbon_footprints"][0]["boundary"] = "gate_to_moon" + fil.write_text(json.dumps(doc), encoding="utf-8") + assert any("gate_to_moon" in m for m in schema_errors()) + + +def make_db(): + db = Database() + db.brands = [ + { + "id": "b1", + "name": "Acme", + "slug": "acme", + "origin": "US", + "website": "https://a.co", + "logo_name": "acme.png", + } + ] + db.materials = [ + {"id": "m1", "brand_id": "b1", "material": "PETG", "slug": "PETG", "material_class": "FFF"} + ] + db.filaments = [ + { + "id": "f1", + "brand_id": "b1", + "material_id": "m1", + "name": "PETG", + "slug": "petg", + "material": "PETG", + "density": 1.27, + "diameter_tolerance": 0.02, + "discontinued": False, + "sustainability": {"carbon_footprints": [PETG_FOOTPRINT]}, + } + ] + db.variants = [ + { + "id": "v1", + "filament_id": "f1", + "name": "Black", + "slug": "black", + "color_hex": "#000000", + "discontinued": False, + "sustainability": {"relative_claims": []}, + } + ] + db.sizes = [ + { + "id": "s1", + "variant_id": "v1", + "filament_weight": 1000, + "diameter": 1.75, + "container_material": "mixed", + "container_details": CONTAINER_DETAILS, + "discontinued": False, + } + ] + return db + + +def test_sqlite_stores_sustainability_as_json(tmp_path): + export_sqlite(make_db(), str(tmp_path), "v", "now") + conn = sqlite3.connect(tmp_path / "sqlite" / "filaments.db") + (fil,) = conn.execute("SELECT sustainability FROM filament").fetchone() + (var,) = conn.execute("SELECT sustainability FROM variant").fetchone() + material, details = conn.execute( + "SELECT container_material, container_details FROM size" + ).fetchone() + conn.close() + + assert json.loads(fil)["carbon_footprints"][0]["value_kg_co2e"] == 5.85 + assert json.loads(var) == {"relative_claims": []} + assert material == "mixed" + assert json.loads(details)["certifications"] == ["FSC"] + + +def test_csv_has_sustainability_columns(tmp_path): + export_csv(make_db(), str(tmp_path), "v", "now") + csv_dir = tmp_path / "csv" + with open(next(csv_dir.glob("filament*.csv")), encoding="utf-8") as f: + row = next(csv.DictReader(f)) + assert json.loads(row["sustainability"])["carbon_footprints"][0]["tool"] == "SimaPro 9.3.0.2" + with open(next(csv_dir.glob("size*.csv")), encoding="utf-8") as f: + assert "container_details" in next(csv.DictReader(f)) diff --git a/webui/src/lib/components/entity/SustainabilityDisplay.svelte b/webui/src/lib/components/entity/SustainabilityDisplay.svelte new file mode 100644 index 0000000000..b6c312eda5 --- /dev/null +++ b/webui/src/lib/components/entity/SustainabilityDisplay.svelte @@ -0,0 +1,163 @@ + + +{#snippet origin(o: Origin)} + {#if o === 'filament'} + (from filament) + {:else if o === 'variant'} + (overrides filament) + {/if} +{/snippet} + +{#snippet source(entry: SourcedEntry)} +
+ + Source{entry.source_type === 'secondary' ? ' (secondary)' : ''}, retrieved {entry.retrieved} + +
+ β€œ{entry.source_quote}” +
+ + + {entry.source_url} + + + {#if entry.notes}

{entry.notes}

{/if} +
+{/snippet} + +{#snippet badge(text: string, warn = false)} + {text} +{/snippet} + +
+ {#if recycled.value} + {@const r = recycled.value} +
+
+ Recycled content: + {pct(r.pct, r.pct_qualifier)} + {@render badge(enumLabel(r.type))} + {@render badge(enumLabel(r.evidence))} + {@render origin(recycled.origin)} +
+ {@render source(r)} +
+ {/if} + + {#if bio.value} + {@const b = bio.value} +
+
+ Bio-based content: + {pct(b.pct, b.pct_qualifier)} + {@render badge(enumLabel(b.method))} + {@render origin(bio.origin)} +
+ {@render source(b)} +
+ {/if} + + {#each footprints.value ?? [] as f, i (i)} +
+
+ Carbon footprint: + {f.value_kg_co2e} kg COβ‚‚e {UNIT_LABELS[f.declared_unit] ?? ''} + {#if f.declared_unit === 'unknown'}{@render badge('Unit not stated', true)}{/if} + {@render badge( + BOUNDARY_LABELS[f.boundary] ?? enumLabel(f.boundary), + f.boundary === 'unknown' + )} + {@render badge(`Packaging: ${f.packaging_included}`)} + {@render badge(f.method.toUpperCase() === 'LCA' ? 'LCA' : enumLabel(f.method))} + {@render badge( + f.verification === 'none' ? 'Not verified' : enumLabel(f.verification), + f.verification === 'none' + )} + {#if !f.publicly_available}{@render badge('Study on request')}{/if} + {#if i === 0}{@render origin(footprints.origin)}{/if} +
+ {#if f.tool || f.practitioner || f.published || f.standard} +

+ {[f.standard, f.tool, f.practitioner, f.published ? `published ${f.published}` : null] + .filter(Boolean) + .join(' Β· ')} +

+ {/if} + {@render source(f)} +
+ {/each} + + {#each claims.value ?? [] as c, i (i)} +
+
+ Relative claim: + {c.reduction_pct}% lower {c.metric === 'gwp' ? 'GWP' : ''} than β€œ{c.baseline}” + {#if i === 0}{@render origin(claims.origin)}{/if} +
+ {@render source(c)} +
+ {/each} +
diff --git a/webui/src/lib/components/entity/index.ts b/webui/src/lib/components/entity/index.ts index 354811c57f..b350f56cdb 100644 --- a/webui/src/lib/components/entity/index.ts +++ b/webui/src/lib/components/entity/index.ts @@ -7,3 +7,4 @@ export { default as ChildListPanel } from './ChildListPanel.svelte'; export { default as SubmittedBanner } from './SubmittedBanner.svelte'; export { default as InFlightHint } from './InFlightHint.svelte'; export { default as OrcaDownloadButton } from './OrcaDownloadButton.svelte'; +export { default as SustainabilityDisplay } from './SustainabilityDisplay.svelte'; diff --git a/webui/src/lib/components/form-fields/SizeCard.svelte b/webui/src/lib/components/form-fields/SizeCard.svelte index 49964b4a11..4fd73c80d7 100644 --- a/webui/src/lib/components/form-fields/SizeCard.svelte +++ b/webui/src/lib/components/form-fields/SizeCard.svelte @@ -1,7 +1,9 @@
@@ -163,11 +173,42 @@ +
+ + {#if containerDetailsSchema} + {#if value.container_details} +
+
+ Container details (sourced) + +
+ } + schema={containerDetailsSchema} + idPrefix="size-{id}-container" + valueFields={VALUE_FIELDS.container_details} + /> +
+ {:else} + + {/if} + {/if} +
diff --git a/webui/src/lib/components/form-fields/SourcedEntryFields.svelte b/webui/src/lib/components/form-fields/SourcedEntryFields.svelte new file mode 100644 index 0000000000..26398f2185 --- /dev/null +++ b/webui/src/lib/components/form-fields/SourcedEntryFields.svelte @@ -0,0 +1,105 @@ + + +
+ {#each fields as [key, prop] (key)} + {@const id = `${idPrefix}-${key}`} + {@const t = schemaTypes(prop)} +
+ {#if key === 'source_url'} + entry[key] ?? '', (v) => (entry[key] = v)} + {id} + label={label(key, prop)} + required={required.has(key)} + tooltip={prop.description ?? ''} + compact + /> + {:else} + + {#if Array.isArray(prop.enum)} + + {:else if t.includes('boolean')} + + {:else if t.includes('number') || t.includes('integer')} + setNumber(key, e.currentTarget.value)} + class={INPUT_COMPACT_CLASSES} + placeholder={t.includes('null') ? 'Not stated' : ''} + /> + {:else if t.includes('array')} + entry[key] ?? [], (v) => (entry[key] = v)} + placeholder="Add..." + /> + {:else if prop.format === 'date'} + + {:else if TEXTAREA.has(key)} + + {:else} + + {/if} + {/if} +
+ {/each} +
+ +{#each problems as problem (problem)} + +{/each} diff --git a/webui/src/lib/components/form-fields/SustainabilityEditor.svelte b/webui/src/lib/components/form-fields/SustainabilityEditor.svelte new file mode 100644 index 0000000000..89b63dc55c --- /dev/null +++ b/webui/src/lib/components/form-fields/SustainabilityEditor.svelte @@ -0,0 +1,138 @@ + + +
+

+ Copy every figure exactly as the source writes it, and paste the sentence it appears in. Never + derive, average or convert. Leave out offsets, "carbon neutral" and other generic green claims. + {note} +

+ + {#each OBJECT_SECTIONS as section (section)} + {#if value[section]} +
+
+

{title(section)}

+ +
+ +
+ {/if} + {/each} + + {#each ARRAY_SECTIONS as section (section)} + {#each value[section] ?? [] as entry, i (entry)} +
+
+

+ + {title(section)} + {i + 1} +

+ +
+ +
+ {/each} + {/each} + +
+ {#each OBJECT_SECTIONS as section (section)} + {#if !value[section]} + + {/if} + {/each} + {#each ARRAY_SECTIONS as section (section)} + + {/each} +
+
diff --git a/webui/src/lib/components/form-fields/__tests__/SustainabilityEditor.test.ts b/webui/src/lib/components/form-fields/__tests__/SustainabilityEditor.test.ts new file mode 100644 index 0000000000..a0387f1519 --- /dev/null +++ b/webui/src/lib/components/form-fields/__tests__/SustainabilityEditor.test.ts @@ -0,0 +1,43 @@ +import { describe, it, expect } from 'vitest'; +import { render, screen, fireEvent } from '@testing-library/svelte'; +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import Harness from './SustainabilityEditorHarness.svelte'; + +const schema = JSON.parse( + readFileSync(resolve(__dirname, '../../../../../../schemas/sustainability_schema.json'), 'utf-8') +); + +describe('SustainabilityEditor', () => { + it('adds a carbon footprint card when its button is pressed', async () => { + render(Harness, { schema }); + const add = screen.getByRole('button', { name: /Carbon Footprints/ }); + await fireEvent.click(add); + expect(screen.getByTestId('value').textContent).toContain('carbon_footprints'); + expect(screen.getByText(/Carbon Footprints 1/)).toBeTruthy(); + }); + + it('adds and removes a recycled content section', async () => { + render(Harness, { schema }); + await fireEvent.click(screen.getByRole('button', { name: /Recycled Content/ })); + expect(screen.getByTestId('value').textContent).toContain('recycled_content'); + await fireEvent.click(screen.getByTitle('Remove Recycled Content')); + expect(screen.getByTestId('value').textContent).not.toContain('recycled_content'); + }); +}); + +describe('SourcedEntryFields', () => { + it('renders container details with no URL or certifications yet', async () => { + const { default: SourcedEntryFields } = await import('../SourcedEntryFields.svelte'); + const sizes = JSON.parse( + readFileSync(resolve(__dirname, '../../../../../../schemas/sizes_schema.json'), 'utf-8') + ); + render(SourcedEntryFields, { + entry: { source_type: 'primary', retrieved: '2026-10-26' }, + schema: sizes.items.properties.container_details, + idPrefix: 'size-1-container', + valueFields: ['recycled_pct'] + }); + expect(screen.getByText('Certifications')).toBeTruthy(); + }); +}); diff --git a/webui/src/lib/components/form-fields/__tests__/SustainabilityEditorHarness.svelte b/webui/src/lib/components/form-fields/__tests__/SustainabilityEditorHarness.svelte new file mode 100644 index 0000000000..b6eff0d90c --- /dev/null +++ b/webui/src/lib/components/form-fields/__tests__/SustainabilityEditorHarness.svelte @@ -0,0 +1,11 @@ + + + +
{JSON.stringify(value)}
diff --git a/webui/src/lib/components/form-fields/index.ts b/webui/src/lib/components/form-fields/index.ts index 4eb114577a..79023183aa 100644 --- a/webui/src/lib/components/form-fields/index.ts +++ b/webui/src/lib/components/form-fields/index.ts @@ -18,3 +18,5 @@ export { default as StoreSelect } from './StoreSelect.svelte'; export { default as PurchaseLinkCard } from './PurchaseLinkCard.svelte'; export { default as PurchaseLinksSection } from './PurchaseLinksSection.svelte'; export { default as SizeCard } from './SizeCard.svelte'; +export { default as SourcedEntryFields } from './SourcedEntryFields.svelte'; +export { default as SustainabilityEditor } from './SustainabilityEditor.svelte'; diff --git a/webui/src/lib/components/forms/FilamentForm.svelte b/webui/src/lib/components/forms/FilamentForm.svelte index a308a97e8a..c170a60049 100644 --- a/webui/src/lib/components/forms/FilamentForm.svelte +++ b/webui/src/lib/components/forms/FilamentForm.svelte @@ -1,7 +1,7 @@ @@ -921,6 +1005,30 @@
{/if} + + + {#if sustainabilitySchema} +
+

+ Sustainability + +

+ {#if recycledTraitIssue} + + {/if} + +
+ {/if} {/snippet} {#snippet rightColumnContent()} @@ -970,6 +1078,7 @@ onAddLink={() => addPurchaseLink(sizeIndex)} onRemoveLink={(linkIndex) => removePurchaseLink(sizeIndex, linkIndex)} {sharedWith} + containerDetailsSchema={containerDetailsSchema()} /> {/each} {:else} diff --git a/webui/src/lib/server/cloudValidator.ts b/webui/src/lib/server/cloudValidator.ts index 990294a146..1334d7bc71 100644 --- a/webui/src/lib/server/cloudValidator.ts +++ b/webui/src/lib/server/cloudValidator.ts @@ -3,6 +3,7 @@ * No subprocess spawning β€” all validation runs in-process. */ import Ajv, { type ErrorObject } from 'ajv'; +import { promises as fs } from 'fs'; import { API_BASE } from './cloudProxy'; import { SAFE_SEGMENT, cleanEntityData } from './saveUtils'; import type { Job } from './jobManager'; @@ -30,9 +31,9 @@ interface ValidationResult { // --- Schema cache --- const SCHEMA_NAMES = ['brand', 'material', 'filament', 'variant', 'store', 'sizes', 'material_types'] as const; -type SchemaName = (typeof SCHEMA_NAMES)[number]; +type SchemaName = (typeof SCHEMA_NAMES)[number] | 'sustainability'; -import { ENTITY_CONFIGS } from './entityConfig'; +import { ENTITY_CONFIGS, SCHEMA_DIR } from './entityConfig'; const ALLOWED_ENTITY_TYPES = new Set(Object.keys(ENTITY_CONFIGS)); const ALLOWED_OPERATIONS = new Set(['create', 'update', 'delete']); const MAX_CHANGES = 500; @@ -148,13 +149,35 @@ function resolveExternalRefs(schema: unknown, refMap: Record): u return result; } +/** + * The sustainability sub-schema, never fatal: it is not prefetched, so a deployed API + * that predates it cannot block every submission. Falls back to the checkout's copy, + * then to a permissive object (CI's ofd-validator still checks the block in full). + */ +async function fetchSustainabilitySchema(): Promise { + try { + return await fetchSchema('sustainability'); + } catch { + try { + const content = await fs.readFile(`${SCHEMA_DIR}/sustainability_schema.json`, 'utf-8'); + return JSON.parse(content); + } catch { + return { type: 'object' }; + } + } +} + async function compileValidator(entityType: SchemaName) { const ajv = createAjvInstance(); // Inline external $refs so AJV never needs to resolve relative URIs - const materialTypesSchema = await fetchSchema('material_types'); + const [materialTypesSchema, sustainabilitySchema] = await Promise.all([ + fetchSchema('material_types'), + fetchSustainabilitySchema() + ]); const refMap: Record = { - './material_types_schema.json': materialTypesSchema + './material_types_schema.json': materialTypesSchema, + './sustainability_schema.json': sustainabilitySchema }; const rawSchema = await fetchSchema(entityType); diff --git a/webui/src/lib/server/schemaHandler.ts b/webui/src/lib/server/schemaHandler.ts index d6043d7599..f5c6a0390f 100644 --- a/webui/src/lib/server/schemaHandler.ts +++ b/webui/src/lib/server/schemaHandler.ts @@ -9,15 +9,26 @@ import { IS_CLOUD, proxyGetToCloud } from './cloudProxy'; * @param schemaName - e.g., 'brand', 'material', 'filament', 'store', 'variant' */ export function createSchemaHandler(schemaName: string) { + const readLocal = async () => { + const schemaPath = `${SCHEMA_DIR}/${schemaName}_schema.json`; + return JSON.parse(await fs.readFile(schemaPath, 'utf-8')); + }; + return async () => { if (IS_CLOUD) { - return proxyGetToCloud(`/api/schemas/${schemaName}`); + const response = await proxyGetToCloud(`/api/schemas/${schemaName}`); + if (response.status !== 404) return response; + // A schema newer than the deployed API: serve the repo's copy when this + // server runs from a checkout (the Docker image has none, so it stays 404). + try { + return json(await readLocal()); + } catch { + return response; + } } try { - const schemaPath = `${SCHEMA_DIR}/${schemaName}_schema.json`; - const content = await fs.readFile(schemaPath, 'utf-8'); - return json(JSON.parse(content)); + return json(await readLocal()); } catch (error) { console.error(`Error reading ${schemaName} schema:`, error); return json({ error: 'Schema not found' }, { status: 404 }); diff --git a/webui/src/lib/services/schemaService.ts b/webui/src/lib/services/schemaService.ts index fc168df19f..5c1d32d80d 100644 --- a/webui/src/lib/services/schemaService.ts +++ b/webui/src/lib/services/schemaService.ts @@ -162,7 +162,8 @@ export const SCHEMA_NAMES = { filament: 'filament_schema.json', variant: 'variant_schema.json', store: 'store_schema.json', - materialTypes: 'material_types_schema.json' + materialTypes: 'material_types_schema.json', + sustainability: 'sustainability_schema.json' } as const; /** @@ -175,7 +176,8 @@ export const ENTITY_ROUTES = { filament: 'filament', variant: 'variant', store: 'store', - materialTypes: 'material_types' + materialTypes: 'material_types', + sustainability: 'sustainability' } as const; export type SchemaName = keyof typeof SCHEMA_NAMES; @@ -194,6 +196,10 @@ export async function fetchEntitySchema(entityType: SchemaName): Promise; +/** + * Entity types derived from the schema service's SCHEMA_NAMES registry. + * materialTypes and sustainability are sub-schemas pulled in by `$ref`, not entities. + */ +export type EntityType = Exclude; export type ChangeOperation = 'create' | 'update' | 'delete'; diff --git a/webui/src/lib/types/database.ts b/webui/src/lib/types/database.ts index 4ce47f68f4..5dd3fa4e3d 100644 --- a/webui/src/lib/types/database.ts +++ b/webui/src/lib/types/database.ts @@ -70,11 +70,92 @@ export interface Filament { discontinued?: boolean; slicer_ids?: any; slicer_settings?: any; + sustainability?: Sustainability; brandId?: string; materialType?: string; filamentDir?: string; } +// --- Sustainability (schemas/sustainability_schema.json) --------------------- +// Every figure is copied verbatim from a cited source; see docs/manual.md. + +export type SourceType = 'primary' | 'secondary'; +export type PctQualifier = 'exact' | 'up_to' | 'at_least'; + +/** Fields every sourced sustainability entry carries. */ +export interface SourcedEntry { + source_type: SourceType; + source_url: string; + /** Verbatim text from the source; must contain the number as written. */ + source_quote: string; + /** YYYY-MM-DD */ + retrieved: string; + notes?: string | null; +} + +export interface RecycledContent extends SourcedEntry { + /** 0-100; null when the source gives no number. */ + pct: number | null; + pct_qualifier?: PctQualifier; + type: 'post_industrial' | 'post_consumer' | 'mixed' | 'unknown'; + evidence: 'iso_14021' | 'third_party_certified' | 'supplier_declaration' | 'marketing'; +} + +export interface BioBasedContent extends SourcedEntry { + pct: number | null; + pct_qualifier?: PctQualifier; + method: 'astm_d6866' | 'en_16785' | 'declared'; +} + +export interface CarbonFootprint extends SourcedEntry { + value_kg_co2e: number; + declared_unit: 'per_kg_filament' | 'per_spool_as_sold' | 'unknown'; + boundary: + | 'resin_cradle_to_gate' + | 'filament_cradle_to_gate' + | 'cradle_to_customer' + | 'cradle_to_grave' + | 'unknown'; + packaging_included: 'yes' | 'no' | 'unknown'; + biogenic_carbon: 'included' | 'excluded' | 'reported_separately' | 'unknown'; + recycled_allocation: 'cut_off' | 'burden_free_scrap' | 'other' | 'unknown' | 'not_applicable'; + method: 'epd' | 'iso_14067' | 'lca' | 'declaration'; + standard?: string | null; + tool?: string | null; + practitioner?: string | null; + verification: 'none' | 'peer_review' | 'third_party' | 'epd_registered'; + verifier?: string | null; + epd_registration_number?: string | null; + /** false when the study is only available on request. */ + publicly_available: boolean; + reference_year?: number | null; + published?: string | null; +} + +export interface RelativeClaim extends SourcedEntry { + reduction_pct: number; + metric: 'gwp' | 'other'; + /** Verbatim from the source. */ + baseline: string; +} + +/** + * On a variant, each field set here replaces the filament's field of the same name; + * carbon_footprints and relative_claims replace the whole array. + */ +export interface Sustainability { + recycled_content?: RecycledContent; + bio_based_content?: BioBasedContent; + carbon_footprints?: CarbonFootprint[]; + relative_claims?: RelativeClaim[]; +} + +export interface ContainerDetails extends SourcedEntry { + recycled_pct?: number | null; + pct_qualifier?: PctQualifier; + certifications?: string[]; +} + export interface PurchaseLink { store_id: string; url: string; @@ -97,10 +178,11 @@ export interface VariantSize { /** @deprecated Use `container_material: 'refill'`; read through `containerMaterialOf`. */ spool_refill?: boolean; container_material?: ContainerMaterial; + container_details?: ContainerDetails; purchase_links?: PurchaseLink[]; } -export type ContainerMaterial = 'plastic' | 'cardboard' | 'refill'; +export type ContainerMaterial = 'plastic' | 'cardboard' | 'mixed' | 'refill'; export interface VariantTraits { translucent?: boolean; @@ -191,6 +273,8 @@ export interface Variant { color_hex: string | string[]; discontinued: boolean; traits?: VariantTraits; + /** Per-field override of the filament's sustainability data. */ + sustainability?: Sustainability; sizes?: VariantSize[]; brandId?: string; materialType?: string; diff --git a/webui/src/lib/utils/__tests__/dataQuality.test.ts b/webui/src/lib/utils/__tests__/dataQuality.test.ts index 5ff59658ee..97754c5ed8 100644 --- a/webui/src/lib/utils/__tests__/dataQuality.test.ts +++ b/webui/src/lib/utils/__tests__/dataQuality.test.ts @@ -14,8 +14,14 @@ import { findSharedPurchaseLinks, suggestTraitsFromSiblings, findRedundantSizes, - findDuplicateName + findDuplicateName, + containerMaterialOf, + numberPattern, + checkSourcedEntry, + checkRecycledTrait, + effectiveSustainability } from '../dataQuality'; +import type { RecycledContent } from '$lib/types/database'; describe('isTitleCased', () => { it('accepts a title-cased name', () => { @@ -439,3 +445,88 @@ describe('findDuplicateName', () => { expect(findDuplicateName('Silk', [{ name: '' }, { name: '---' }])).toBeNull(); }); }); + +// --- Sustainability data (mirrors the sustainability tests in test_data_quality.py) -- + +const SOURCE = { + source_type: 'primary' as const, + source_url: 'https://blog.prusa3d.com/introducing-prusament-petg-recycled/', + retrieved: '2026-10-21' +}; + +function recycled(pct: number | null): RecycledContent { + return { + pct, + type: 'post_industrial', + evidence: 'supplier_declaration', + ...SOURCE, + source_quote: 'made from 100% recycled material' + }; +} + +describe('containerMaterialOf', () => { + it('keeps mixed (cardboard core, plastic sides)', () => { + expect(containerMaterialOf({ container_material: 'mixed' })).toBe('mixed'); + }); +}); + +describe('numberPattern', () => { + it.each([ + [5.85, 'The results show 5.85 kg of CO2', true], + [5.85, '5,85 kg', true], + [5.85, '15.85 kg', false], + [5.85, '5.851 kg', false], + [100, '100% recycled', true], + [100, '1000 spools', false], + [2.5, '2.50 kg', true] + ])('%s in %j -> %s', (value, quote, expected) => { + expect(numberPattern(value).test(quote)).toBe(expected); + }); +}); + +describe('checkSourcedEntry', () => { + const today = '2026-10-26'; + + it('accepts a sourced footprint', () => { + const entry = { value_kg_co2e: 5.85, ...SOURCE, source_quote: 'show 5.85 kg of CO2' }; + expect(checkSourcedEntry(entry, ['value_kg_co2e'], today)).toEqual([]); + }); + + it('flags a number missing from the quote', () => { + const entry = { value_kg_co2e: 5.85, ...SOURCE, source_quote: 'about six kilograms' }; + const problems = checkSourcedEntry(entry, ['value_kg_co2e'], today); + expect(problems).toHaveLength(1); + expect(problems[0]).toContain('does not contain that number'); + }); + + it('flags missing sources, out-of-range pct and future dates', () => { + const entry = { pct: 120, source_quote: '120%', retrieved: '2999-01-01', reference_year: 2999 }; + const problems = checkSourcedEntry(entry, ['pct'], today); + expect(problems.some((p) => p.startsWith('Missing source_url'))).toBe(true); + expect(problems.some((p) => p.includes('between 0 and 100'))).toBe(true); + expect(problems.filter((p) => p.includes('in the future'))).toHaveLength(2); + }); +}); + +describe('checkRecycledTrait', () => { + it('errors when recycled pct > 0 but the trait is missing', () => { + expect(checkRecycledTrait({ recycled_content: recycled(100) }, undefined, false)?.level).toBe( + 'error' + ); + }); + + it('lets a variant override replace the filament value', () => { + expect( + checkRecycledTrait({ recycled_content: recycled(100) }, { recycled_content: recycled(0) }, false) + ).toBeNull(); + expect( + effectiveSustainability({ recycled_content: recycled(100) }, { recycled_content: recycled(0) }) + .recycled_content?.pct + ).toBe(0); + }); + + it('is silent for the trait alone until a sustainability block exists', () => { + expect(checkRecycledTrait(undefined, undefined, true)).toBeNull(); + expect(checkRecycledTrait({ relative_claims: [] }, undefined, true)?.level).toBe('warning'); + }); +}); diff --git a/webui/src/lib/utils/__tests__/sustainability.test.ts b/webui/src/lib/utils/__tests__/sustainability.test.ts new file mode 100644 index 0000000000..7a54651f40 --- /dev/null +++ b/webui/src/lib/utils/__tests__/sustainability.test.ts @@ -0,0 +1,59 @@ +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import { entrySchema, newEntry, pruneEntry, pruneSustainability } from '../sustainability'; + +// The real schema, so these tests break if the schema and the editor drift apart. +const schema = JSON.parse( + readFileSync(resolve(__dirname, '../../../../../schemas/sustainability_schema.json'), 'utf-8') +); + +describe('newEntry', () => { + it('starts unclear fields as unknown and stamps today as retrieved', () => { + const entry = newEntry(entrySchema(schema, 'carbon_footprints'), '2026-10-26'); + expect(entry.declared_unit).toBe('unknown'); + expect(entry.boundary).toBe('unknown'); + expect(entry.packaging_included).toBe('unknown'); + expect(entry.source_type).toBe('primary'); + expect(entry.retrieved).toBe('2026-10-26'); + // No value is guessed. + expect(entry.value_kg_co2e).toBeUndefined(); + }); + + it('uses schema defaults', () => { + expect(newEntry(entrySchema(schema, 'recycled_content')).pct_qualifier).toBe('exact'); + }); +}); + +describe('pruneEntry', () => { + it('keeps a required nullable pct as null and drops empty optional fields', () => { + const out = pruneEntry( + { pct: '', type: 'post_industrial', notes: ' ', source_quote: ' made from scrap ' }, + entrySchema(schema, 'recycled_content') + ); + expect(out).toEqual({ pct: null, type: 'post_industrial', source_quote: 'made from scrap' }); + }); + + it('drops keys the schema does not know', () => { + const out = pruneEntry( + { reduction_pct: 78, offset_trees: 5 }, + entrySchema(schema, 'relative_claims') + ); + expect(out).toEqual({ reduction_pct: 78 }); + }); +}); + +describe('pruneSustainability', () => { + it('returns undefined for an empty block', () => { + expect(pruneSustainability({}, schema)).toBeUndefined(); + expect(pruneSustainability({ carbon_footprints: [] }, schema)).toBeUndefined(); + }); + + it('keeps sections that have entries', () => { + const out = pruneSustainability( + { relative_claims: [{ reduction_pct: 78, metric: 'gwp' } as never] }, + schema + ); + expect(out?.relative_claims?.[0]).toMatchObject({ reduction_pct: 78, metric: 'gwp' }); + }); +}); diff --git a/webui/src/lib/utils/__tests__/urlSanitizer.test.ts b/webui/src/lib/utils/__tests__/urlSanitizer.test.ts index 9322ebd64b..dec5492e21 100644 --- a/webui/src/lib/utils/__tests__/urlSanitizer.test.ts +++ b/webui/src/lib/utils/__tests__/urlSanitizer.test.ts @@ -167,6 +167,18 @@ describe('stripTrackersDeep', () => { expect(out.data_sheet_url).toBe('https://x.com/ds.pdf'); expect(out.name).toBe('Brand'); }); + it('strips source_url nested in sustainability entries', () => { + const out = stripTrackersDeep({ + sustainability: { + carbon_footprints: [ + { source_url: 'https://blog.prusa3d.com/x_65806/?utm_source=nl', source_quote: '5.85 kg' } + ] + } + }); + expect(out.sustainability.carbon_footprints[0].source_url).toBe( + 'https://blog.prusa3d.com/x_65806/' + ); + }); }); describe('SimplyPrint recommender params', () => { diff --git a/webui/src/lib/utils/dataQuality.ts b/webui/src/lib/utils/dataQuality.ts index 48c5046241..64ce1af871 100644 --- a/webui/src/lib/utils/dataQuality.ts +++ b/webui/src/lib/utils/dataQuality.ts @@ -16,7 +16,7 @@ * shared `schemas/trait_rules.json` table (via `/api/trait-rules`) and is wired into `VariantForm`. */ -import type { ContainerMaterial } from '$lib/types/database'; +import type { ContainerMaterial, Sustainability } from '$lib/types/database'; /** Words that legitimately stay lowercase inside a title-cased display name. */ const MINOR_WORDS = new Set([ @@ -171,7 +171,13 @@ export function containerMaterialOf(size: { spool_refill?: unknown; }): ContainerMaterial | undefined { const material = size.container_material; - if (material === 'plastic' || material === 'cardboard' || material === 'refill') return material; + if ( + material === 'plastic' || + material === 'cardboard' || + material === 'mixed' || + material === 'refill' + ) + return material; return size.spool_refill === true ? 'refill' : undefined; } @@ -389,3 +395,116 @@ export function findDuplicateName( } return wordOrder ? { match: wordOrder, kind: 'word-order' } : null; } + +// --- Sustainability data ------------------------------------------------------ +// +// "Copy, never compute": every figure is copied from a cited source and the quote must +// show it. Mirrors the sustainability rules in `ofd/validation/data_quality.py`. + +const SOURCE_FIELDS = ['source_url', 'source_quote', 'retrieved'] as const; + +/** + * Matches `value` as written in prose: `5.85` or `5,85`, trailing zeros allowed. + * The digit boundaries stop `5.85` from matching inside `15.85` or `5.851`. + */ +export function numberPattern(value: number): RegExp { + const text = String(value); + const [intPart, frac] = text.split('.'); + const number = frac ? `${intPart}[.,]${frac}0*` : `${intPart}(?:[.,]0+)?`; + return new RegExp(`(? | null | undefined, + valueFields: string[], + today: string = todayIso() +): string[] { + if (!entry || typeof entry !== 'object') return []; + const problems: string[] = []; + + const missing = SOURCE_FIELDS.filter((f) => !String(entry[f] ?? '').trim()); + if (missing.length) { + problems.push( + `Missing ${missing.join(', ')}. Every figure needs a source URL, a verbatim quote and the date it was retrieved.` + ); + } + + const quote = typeof entry.source_quote === 'string' ? entry.source_quote : ''; + for (const field of valueFields) { + const value = entry[field]; + if (typeof value !== 'number' || Number.isNaN(value)) continue; + if (field !== 'value_kg_co2e' && (value < 0 || value > 100)) { + problems.push(`${field} is ${value}; a percentage must be between 0 and 100.`); + } + if (quote.trim() && !numberPattern(value).test(quote)) { + problems.push( + `${field} is ${value}, but the quote does not contain that number. Copy the figure exactly as the source writes it.` + ); + } + } + + for (const field of ['retrieved', 'published']) { + const raw = entry[field]; + if (typeof raw !== 'string' || !raw) continue; + if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) { + problems.push(`${field} must be a date as YYYY-MM-DD.`); + } else if (raw > today) { + problems.push(`${field} ${raw} is in the future.`); + } + } + const year = entry.reference_year; + if (typeof year === 'number' && year > Number(today.slice(0, 4))) { + problems.push(`reference_year ${year} is in the future.`); + } + + return problems; +} + +/** + * The effective sustainability block of a variant: each field the variant sets replaces + * the filament's field of the same name. + */ +export function effectiveSustainability( + filament: Sustainability | undefined, + variant: Sustainability | undefined +): Sustainability { + return { ...(filament ?? {}), ...(variant ?? {}) }; +} + +/** + * `recycled_content` and `traits.recycled` must agree on a variant. A positive + * percentage without the trait is an error; the trait with no recycled content is + * only a warning, and only once a sustainability block exists. + */ +export function checkRecycledTrait( + filament: Sustainability | undefined, + variant: Sustainability | undefined, + hasRecycledTrait: boolean +): { level: 'error' | 'warning'; message: string } | null { + const content = effectiveSustainability(filament, variant).recycled_content; + const pct = content?.pct; + if (typeof pct === 'number' && pct > 0 && !hasRecycledTrait) { + return { + level: 'error', + message: `Recycled content is ${pct}% but the Recycled trait is not set.` + }; + } + const hasBlock = + Object.keys(filament ?? {}).length > 0 || Object.keys(variant ?? {}).length > 0; + if (hasRecycledTrait && hasBlock && (!content || pct === 0)) { + return { + level: 'warning', + message: 'The Recycled trait is set and sustainability data exists, but there is no recycled content.' + }; + } + return null; +} diff --git a/webui/src/lib/utils/sustainability.ts b/webui/src/lib/utils/sustainability.ts new file mode 100644 index 0000000000..201f25efb1 --- /dev/null +++ b/webui/src/lib/utils/sustainability.ts @@ -0,0 +1,138 @@ +/** + * Helpers for editing `sustainability` blocks and `container_details` against + * schemas/sustainability_schema.json and schemas/sizes_schema.json. + * + * The editor is driven by the schema (enums, descriptions, required fields), so these + * helpers only create blank entries and strip what the contributor left empty. + */ + +import type { Sustainability } from '$lib/types/database'; + +/** The subset of JSON Schema the sustainability editor reads. */ +export interface JsonSchema { + type?: string | string[]; + title?: string; + description?: string; + properties?: Record; + items?: JsonSchema; + required?: string[]; + enum?: Array; + default?: unknown; + format?: string; + minimum?: number; + maximum?: number; +} + +/** + * One sourced entry. Its fields come from the schema at runtime, so values can be any + * JSON type; the typed views are `RecycledContent`, `CarbonFootprint` etc. + */ +// eslint-disable-next-line @typescript-eslint/no-explicit-any +export type Entry = Record; + +/** Sections that hold one sourced object, and sections that hold a list of them. */ +export const OBJECT_SECTIONS = ['recycled_content', 'bio_based_content'] as const; +export const ARRAY_SECTIONS = ['carbon_footprints', 'relative_claims'] as const; +export type SustainabilitySection = + | (typeof OBJECT_SECTIONS)[number] + | (typeof ARRAY_SECTIONS)[number]; + +/** The number in each section that the source quote must contain. */ +export const VALUE_FIELDS: Record = { + recycled_content: ['pct'], + bio_based_content: ['pct'], + carbon_footprints: ['value_kg_co2e'], + relative_claims: ['reduction_pct'], + container_details: ['recycled_pct'] +}; + +export function schemaTypes(propSchema: JsonSchema | undefined): string[] { + const t = propSchema?.type; + return Array.isArray(t) ? t : t ? [t] : []; +} + +/** The schema for one entry of a section (the object itself, or an array's items). */ +export function entrySchema( + sustainabilitySchema: JsonSchema | null | undefined, + section: SustainabilitySection +): JsonSchema | undefined { + const prop = sustainabilitySchema?.properties?.[section]; + return prop?.type === 'array' ? prop.items : prop; +} + +/** "post_industrial" -> "Post industrial" */ +export function enumLabel(value: string): string { + const text = value.replace(/_/g, ' '); + return text.charAt(0).toUpperCase() + text.slice(1); +} + +function todayIso(): string { + return new Date().toISOString().slice(0, 10); +} + +/** + * A blank entry for `schema`. Unclear values start as "unknown" where the schema + * allows it, so nothing is guessed on the contributor's behalf. + */ +export function newEntry(schema: JsonSchema | undefined, today: string = todayIso()): Entry { + const entry: Entry = {}; + for (const [key, prop] of Object.entries(schema?.properties ?? {})) { + if (prop.default !== undefined) entry[key] = prop.default; + else if (Array.isArray(prop.enum) && prop.enum.includes('unknown')) entry[key] = 'unknown'; + } + entry.source_type = 'primary'; + entry.retrieved = today; + return entry; +} + +function isEmpty(value: unknown): boolean { + return ( + value === undefined || + value === null || + (typeof value === 'number' && Number.isNaN(value)) || + (typeof value === 'string' && value.trim() === '') || + (Array.isArray(value) && value.length === 0) + ); +} + +/** + * Drop empty fields from one entry. A required field that may be null (e.g. `pct` + * when the source gives no number) is kept as `null` rather than dropped. + */ +export function pruneEntry(entry: Entry, schema: JsonSchema | undefined): Entry { + const required = new Set(schema?.required ?? []); + const out: Entry = {}; + for (const [key, value] of Object.entries(entry ?? {})) { + const prop = schema?.properties?.[key]; + if (!prop) continue; + if (isEmpty(value)) { + if (required.has(key) && schemaTypes(prop).includes('null')) out[key] = null; + continue; + } + out[key] = typeof value === 'string' ? value.trim() : value; + } + for (const key of required) { + if (!(key in out) && schemaTypes(schema?.properties?.[key]).includes('null')) out[key] = null; + } + return out; +} + +/** Prune every section and drop the empty ones. Returns undefined when nothing is left. */ +export function pruneSustainability( + value: Sustainability | undefined, + sustainabilitySchema: JsonSchema | null | undefined +): Sustainability | undefined { + if (!value) return undefined; + const out: Record = {}; + for (const section of OBJECT_SECTIONS) { + const entry = value[section]; + if (entry) out[section] = pruneEntry({ ...entry }, entrySchema(sustainabilitySchema, section)); + } + for (const section of ARRAY_SECTIONS) { + const entries = (value[section] ?? []).map((e) => + pruneEntry({ ...e }, entrySchema(sustainabilitySchema, section)) + ); + if (entries.length) out[section] = entries; + } + return Object.keys(out).length ? (out as unknown as Sustainability) : undefined; +} diff --git a/webui/src/lib/utils/urlSanitizer.ts b/webui/src/lib/utils/urlSanitizer.ts index 91290d8492..921e057d26 100644 --- a/webui/src/lib/utils/urlSanitizer.ts +++ b/webui/src/lib/utils/urlSanitizer.ts @@ -169,7 +169,14 @@ export function hasTrackingParams(url: string): boolean { } /** Entity fields that hold a URL (kept in sync with style_data.py's URL_FIELDS). */ -const URL_FIELDS = new Set(['url', 'storefront_url', 'website', 'data_sheet_url', 'safety_sheet_url']); +const URL_FIELDS = new Set([ + 'url', + 'storefront_url', + 'website', + 'data_sheet_url', + 'safety_sheet_url', + 'source_url' +]); /** * Return a deep copy of an entity with tracking params stripped from every known URL field diff --git a/webui/src/routes/api/schemas/sizes/+server.ts b/webui/src/routes/api/schemas/sizes/+server.ts new file mode 100644 index 0000000000..8925126c34 --- /dev/null +++ b/webui/src/routes/api/schemas/sizes/+server.ts @@ -0,0 +1,3 @@ +import { createSchemaHandler } from '$lib/server/schemaHandler'; + +export const GET = createSchemaHandler('sizes'); diff --git a/webui/src/routes/api/schemas/sustainability/+server.ts b/webui/src/routes/api/schemas/sustainability/+server.ts new file mode 100644 index 0000000000..33ba7f5c6e --- /dev/null +++ b/webui/src/routes/api/schemas/sustainability/+server.ts @@ -0,0 +1,3 @@ +import { createSchemaHandler } from '$lib/server/schemaHandler'; + +export const GET = createSchemaHandler('sustainability'); diff --git a/webui/src/routes/brands/[brand]/[material]/[filament]/+page.svelte b/webui/src/routes/brands/[brand]/[material]/[filament]/+page.svelte index f294cd52b7..69031b614f 100644 --- a/webui/src/routes/brands/[brand]/[material]/[filament]/+page.svelte +++ b/webui/src/routes/brands/[brand]/[material]/[filament]/+page.svelte @@ -1,7 +1,7 @@ +{#snippet sustainabilityRender(sustainability: Sustainability)} + +{/snippet} {#snippet certificationsRender(certifications: string[])} {/snippet} @@ -484,6 +488,13 @@ customRender: certificationsRender, fullWidth: true }, + { + key: 'sustainability', + label: 'Sustainability', + hide: (v) => !v || Object.keys(v).length === 0, + customRender: sustainabilityRender, + fullWidth: true + }, { key: 'slicer_settings', label: 'Slicer Settings', @@ -728,6 +739,7 @@ siblingNames={variants.map((v) => v.name)} siblingTraits={variantTraits} {sharedLinkOwners} + filamentSustainability={filament?.sustainability} onSubmit={handleCreateVariant} saving={entityState.creating} /> diff --git a/webui/src/routes/brands/[brand]/[material]/[filament]/[variant]/+page.svelte b/webui/src/routes/brands/[brand]/[material]/[filament]/[variant]/+page.svelte index cbaff4135d..c2797434a5 100644 --- a/webui/src/routes/brands/[brand]/[material]/[filament]/[variant]/+page.svelte +++ b/webui/src/routes/brands/[brand]/[material]/[filament]/[variant]/+page.svelte @@ -1,9 +1,9 @@