yapCAD Metadata Namespace Specification

Version: metadata-namespace-v1.0 Status: Stable – yapCAD 1.0 Scope: Metadata dictionaries attached to solids, surfaces, geometry collections, assemblies, and exported artefacts.

1. Overview

yapCAD embeds metadata alongside geometry objects using dictionary slots (see src/yapcad/metadata.py). This namespace specification formalises those dictionaries so that materials, manufacturing intent, design provenance, and constraints can be shared between authoring tools, automation agents, and downstream exporters.

Every metadata dictionary MUST include:

key	type	description
schema	string	Version identifier, e.g. metadata-namespace-v0.1.
entityId	string	Stable UUID for the geometry entity (use ensure_*_id).
timestamp	string	Optional ISO 8601 timestamp of last update.
tags	string[]	Free-form labels (e.g. ["prototype", "revision-A"]).
layer	string	Logical drawing layer for the entity ("default" if unspecified).

Additional sections are nested dictionaries keyed by namespace names described below. Implementations MAY omit an entire section; consumers must treat unknown sections as opaque extension points.

2. Material Namespace (material)

key	type	notes
name	string	Human-readable descriptor ("6061 Aluminum", "PLA").
standard	string	Reference to published spec ("ASTM B209-14").
grade	string	Alloy/temper or plastic grade ("6061-T6").
density_kg_m3	number	Density if known.
source	string	Supplier, stock number.

3. Manufacturing Namespace (manufacturing)

key	type	notes
process	string	Primary process ("waterjet", "SLA", "3-axis CNC").
instructions	string	Operator notes or setup text.
fixtures	string[]	Fixture/tooling identifiers.
layers	object	Optional map relating drawing layers or geometry subsets to process directives.
postprocessing	string[]	e.g. ["deburr", "anodise-clear"].

4. Design History Namespace (designHistory)

key	type	notes
author	string	Person or agent responsible.
source	string	"prompt", "script", "import" etc.
context	string	Prompt text, script path, or design brief summary.
tools	string[]	Tools/agents used.
iterations	object[]	Chronological entries.

5. Constraint Namespace (constraints)

key	type	notes
mass	object	{ "max_kg": 5.0, "target_kg": 4.2 }.
envelope	object	Bounding box or volume limits.
performance	object[]	Domain-specific constraints (e.g. load, stiffness).
compliance	string[]	Required certifications (["ASME Y14.5-2018"]).

6. Analysis Namespace (analysis)

Captures analysis intent, solver information, and result references for the entity.

key	type	notes
plans	string[]	IDs referencing manifest.validation.plans entries executed against this entity.
loadcases	object[]	Load cases with fields such as id, description, loads, and boundaryConditions.
materials	object	Overrides mapping entity regions to material records.
results	object[]	Normalised summaries referencing validation/results artefacts.
safetyFactors	object	Calculated safety factors per load case, e.g. {"axial-load": 1.8}.
backendHints	object	Optional hints for solver adapters.
notes	string	Free-form context for analysts.

7. Custom Extensions

• Extension namespaces MUST be top-level keys using reverse-domain or organisation prefixes, e.g. "com.example.additive": {...}.

• Extension content MUST NOT overwrite standard namespaces.

8. Usage Guidelines

1. Call ensure_*_id before populating metadata to guarantee entityId.

2. When updating metadata, bump timestamp and keep prior entries in designHistory.iterations.

3. Serialisers SHOULD preserve unknown keys to allow forward compatibility.

4. Exporters SHOULD include the metadata dictionary (or a digest reference) in their manifest entries.

9. Future Work

• Define JSON Schema files for programmatic validation.

• Add localisation support for human-readable strings (multiple languages).

• Align metadata namespace with planned .ycpkg manifest structure.