From 12e300422d5125361411e4d40fbe76b77bb99b34 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Mon, 9 Mar 2026 10:13:15 -0400
Subject: [PATCH] Improve materials/id schema description and examples

The previous description ("An opaque external ID (likely generated by
compiler)") was too vague. The new description explains what resources
the ID identifies, notes the uniqueness constraint, and clarifies
that values can be numeric or string. Examples now use realistic
values matching patterns seen in other schemas.
---
 schemas/materials/id.schema.yaml | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/schemas/materials/id.schema.yaml b/schemas/materials/id.schema.yaml
index 98468e97c..7cd4efe8b 100644
--- a/schemas/materials/id.schema.yaml
+++ b/schemas/materials/id.schema.yaml
@@ -2,12 +2,19 @@ $schema: "https://json-schema.org/draft/2020-12/schema"
 $id: "schema:ethdebug/format/materials/id"
 
 title: ethdebug/format/materials/id
-description: An opaque external ID (likely generated by compiler)
+description: |
+  An opaque identifier for a compilation resource (such as a source
+  file or a compilation itself), typically generated by the compiler.
+  Values may be numeric or string and **must** be unique within the
+  scope where they appear (e.g., source IDs within a single
+  compilation).
 
 type:
   - number
   - string
 
 examples:
-  - 5
-  - "five"
+  # example: numeric source index
+  - 0
+  # example: content-addressed compilation ID
+  - "__301f3b6d85831638"