feat: allow EXAMPLE entries inside NOTE entries (VIM 1993 style)

README.adoc

@@ -341,6 +341,28 @@ Annotations use the same `DetailedDefinition` structure as definitions, notes,
 and examples, with `content` and optional per-item `sources`.
 
 
+== Scoped examples (VIM 1993 style)
+
+A `DetailedDefinition` may carry its own `examples` collection — EXAMPLE entries
+nested inside a NOTE or definition. This follows the VIM 1993 convention where
+examples are scoped to the note or definition they illustrate, rather than
+living at the concept level.
+
+* **Concept-level examples** live on the concept's `examples` collection
+  directly and use `gloss:hasExample`.
+* **Scoped examples** live on a `DetailedDefinition`'s `examples` collection
+  and use `gloss:hasScopedExample` (MECE separation from concept-level).
+
+[source,yaml]
+----
+notes:
+  - content: Resistivity depends on temperature.
+    examples:
+      - content: At 20 °C, annealed copper has a resistivity of 1.68 × 10⁻⁸ Ω·m.
+      - content: For a 1 m copper wire with 1 mm² cross-section, R ≈ 0.017 Ω.
+----
+
+
 == Dataset register
 
 Each dataset directory contains a `register.yaml` — the self-describing metadata

models/concepts/DetailedDefinition.lutaml

@@ -1,6 +1,7 @@
 class DetailedDefinition {
   definition {
-    A definition of the managed term.
+    A definition of the managed term. Reused as the shape for
+    concept-level definition, notes, examples, and annotations.
   }
   +content: ParagraphBlock [1..*] {
     definition {
@@ -12,4 +13,13 @@ class DetailedDefinition {
       Bibliographic references for this particular definition of the managed term.
     }
   }
+  +examples: DetailedDefinition [0..*] {
+    definition {
+      Examples scoped to this entry — e.g. an EXAMPLE nested inside
+      a NOTE (VIM 1993 style) or inside a definition. Empty when
+      the example is concept-level, in which case it lives on
+      Concept#examples directly. Recursive but typically one level
+      deep in source data.
+    }
+  }
 }

ontologies/glossarist.context.jsonld

@@ -57,6 +57,7 @@
     "hasDefinition":       { "@id": "gloss:hasDefinition", "@type": "@id" },
     "hasNote":             { "@id": "gloss:hasNote",       "@type": "@id" },
     "hasExample":          { "@id": "gloss:hasExample",    "@type": "@id" },
+    "hasScopedExample":    { "@id": "gloss:hasScopedExample", "@type": "@id" },
     "hasAnnotation":       { "@id": "gloss:hasAnnotation", "@type": "@id" },
     "hasNonVerbalRep":     { "@id": "gloss:hasNonVerbalRep", "@type": "@id" },
     "domain":              { "@id": "gloss:domain",        "@type": "xsd:anyURI" },

ontologies/glossarist.ttl

@@ -379,7 +379,19 @@ gloss:hasExample a owl:ObjectProperty ;
   rdfs:domain gloss:LocalizedConcept ;
   rdfs:range gloss:DetailedDefinition ;
   rdfs:label "has example"@en ;
-  rdfs:comment "Links a localized concept to an illustrative example."@en .
+  rdfs:comment "Links a localized concept to a concept-level illustrative example."@en .
+
+gloss:hasScopedExample a owl:ObjectProperty ;
+  rdfs:domain gloss:DetailedDefinition ;
+  rdfs:range gloss:DetailedDefinition ;
+  rdfs:label "has scoped example"@en ;
+  rdfs:comment """
+    Links a definition, note, or annotation to a scoped example nested
+    inside it (VIM 1993 style). Distinct from gloss:hasExample, which
+    links a LocalizedConcept to a concept-level example. MECE: concept-
+    level examples use hasExample; definition/note-scoped examples use
+    hasScopedExample.
+  """@en .
 
 gloss:hasAnnotation a owl:ObjectProperty ;
   rdfs:domain gloss:LocalizedConcept ;

ontologies/shapes/glossarist.shacl.ttl

@@ -353,6 +353,10 @@ gloss:DetailedDefinitionShape a sh:NodeShape ;
   sh:property [
     sh:path gloss:hasSource ;
     sh:class gloss:ConceptSource ;
+  ] ;
+  sh:property [
+    sh:path gloss:hasScopedExample ;
+    sh:class gloss:DetailedDefinition ;
   ] .
 
 gloss:ConceptSourceShape a sh:NodeShape ;

schemas/v2/examples/04-definition-notes-examples.yaml

@@ -43,6 +43,15 @@ data:
         - type: lineage
           origin:
             text: "SI Brochure, 9th edition"
+      # Examples scoped to this note — VIM 1993 style nesting.
+      # Concept-level examples (below) are not scoped to a note.
+      examples:
+        - content: >-
+            At 20 °C, annealed copper has a resistivity of about
+            1.68 × 10⁻⁸ Ω·m.
+        - content: >-
+            For a 1 m length of copper wire with cross-section 1 mm²,
+            R ≈ 0.017 Ω.
 
   # Illustrative examples — also DetailedDefinition
   examples:

schemas/v2/localized-concept.yaml

@@ -455,6 +455,12 @@ $defs:
         type: array
         items:
           $ref: "#/$defs/concept_source"
+      examples:
+        type: array
+        items:
+          $ref: "#/$defs/detailed_definition"
+        description: >-
+          Examples scoped to this entry (VIM 1993 style nesting).
         description: Bibliographic references for this particular definition of the concept.
 
   # Data Types

schemas/v3/examples/04-definition-notes-examples.yaml

@@ -34,6 +34,9 @@ data:
       origin:
         ref:
           source: SI Brochure, 9th edition
+    examples:
+    - content: At 20 °C, annealed copper has a resistivity of about 1.68 × 10⁻⁸ Ω·m.
+    - content: For a 1 m length of copper wire with cross-section 1 mm², R ≈ 0.017 Ω.
   examples:
   - content: A copper wire 1 m long with a cross-section of 1 mm² has a resistance
       of approximately 0.017 Ω at 20 °C.

schemas/v3/examples/README.md

@@ -80,8 +80,14 @@ ConceptData defaults → Designation overrides → Pronunciation overrides.
 
 All three use `DetailedDefinition` — text content with optional per-item sources.
 
+A `DetailedDefinition` may carry its own scoped `examples` collection (VIM 1993
+style: EXAMPLE entries nested inside a NOTE). Concept-level examples — the ones
+not scoped to a specific note or definition — live on `Concept#examples`
+directly.
+
 - **`04-definition-notes-examples.yaml`**: definition with authoritative source,
-  two notes (one with lineage source), and an example.
+  two notes (one with lineage source and two scoped examples), and a concept-level
+  example.
 
 ## 05 — Domains (Classification)
 

schemas/v3/localized-concept.yaml

@@ -711,6 +711,15 @@ $defs:
         items:
           $ref: "#/$defs/concept_source"
         description: Bibliographic references for this content.
+      examples:
+        type: array
+        items:
+          $ref: "#/$defs/detailed_definition"
+        description: >-
+          Examples scoped to this entry (VIM 1993 style: EXAMPLE entries
+          nested inside a NOTE or definition). Empty when the example is
+          concept-level, in which case it lives on the concept's
+          top-level examples collection directly.
 
   related_concept:
     type: object