feat: allow EXAMPLE entries inside NOTE entries (VIM 1993 style)#61
Merged
Conversation
Adds `+examples: DetailedDefinition [0..*]` to DetailedDefinition so that any definition, note, example, or annotation can carry scoped examples. Closes #60. Source documents like VIM 1993 nest EXAMPLE entries inside NOTE entries — e.g. NOTE 1 followed by EXAMPLE a) and EXAMPLE b) that belong to that note. The current model flattened both notes and examples at the concept level, with no way to express the scoping. The field is added to DetailedDefinition itself (the shared type) rather than to a new Note subtype, so that: - definitions can also carry inline examples (also seen in VIM) - one change covers all four reuse sites (definition, notes, examples, annotations) without subtype proliferation - the recursion is bounded by data — examples-of-examples do not occur in source documents Concept-level examples (the common case) continue to live on Concept#examples directly; DetailedDefinition#examples is empty for those. Updated example 04 in both v2 and v3 schemas to demonstrate a note with scoped examples alongside a concept-level example. Regenerated Concepts.png. Refs: #60
This was referenced Jun 20, 2026
Merged
PR #61 added +examples to DetailedDefinition.lutaml but missed five layers: - schemas/v3/localized-concept.yaml: add examples to detailed_definition - schemas/v2/localized-concept.yaml: add examples to detailed_definition - ontologies/glossarist.ttl: add gloss:hasScopedExample (MECE with hasExample — concept-level uses hasExample, definition/note-scoped uses hasScopedExample, following the established pattern of hasRelatedConcept vs hasDesignationRelationship) - ontologies/shapes/glossarist.shacl.ttl: add hasScopedExample to DetailedDefinitionShape - ontologies/glossarist.context.jsonld: add hasScopedExample term - README.adoc: document scoped examples (VIM 1993 style) with the MECE distinction between concept-level and scoped examples
ronaldtse
added a commit
to glossarist/glossarist-ruby
that referenced
this pull request
Jun 21, 2026
Adds `examples` attribute to Glossarist::DetailedDefinition and its V2 and V3 subclasses, so any note, definition, or annotation can carry scoped examples — the VIM 1993 style where EXAMPLE entries appear inside a NOTE entry. The attribute is self-referential: `examples` is a collection of DetailedDefinition itself. lutaml-model handles the recursion cleanly via lazy resolution. - Base: `attribute :examples, DetailedDefinition, collection: true, initialize_empty: true` - V2::DetailedDefinition overrides to use V2::DetailedDefinition for the element type (matches the sources override pattern). - V3::DetailedDefinition mirrors V2. Backwards compatible: old YAML without `examples` round-trips unchanged. New YAML adds the `examples:` key only when non-empty. Concept-level examples continue to live on ConceptData#examples directly; this new field is for the scoped/nested case. Requires: glossarist/concept-model#61
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #60. Adds
+examples: DetailedDefinition [0..*]toDetailedDefinitionso any note (or definition, or annotation) can carry scoped EXAMPLE entries — VIM 1993 style.Summary
models/concepts/DetailedDefinition.lutaml— added the recursive+examplesfield with definition text explaining when it's used vsConcept#examples.schemas/v2/examples/04-definition-notes-examples.yamland v3 counterpart — extended to show a note with two scoped examples alongside a concept-level example.schemas/v3/examples/README.md— updated section 04 description.images/Concepts.png— regenerated.Design rationale
The field is added to
DetailedDefinition(the shared type used fordefinition,notes,examples,annotations) rather than to a newNotesubtype. This:Concept-level examples continue to live on
Concept#examplesdirectly;DetailedDefinition#examplesis empty for those. Fully backwards compatible — old YAML round-trips unchanged.Test plan
makesucceeds (all 4 PNGs regenerate, no parse errors)