Add "NoDL fragments" to the schema#80
Closed
emersonknapp wants to merge 2 commits into
Closed
Conversation
emersonknapp
commented
May 28, 2026
| enum: [node, lifecycle_node] | ||
| description: Built-in ROS 2 base node type this node inherits from. | ||
|
|
||
| fragments: |
Member
Author
There was a problem hiding this comment.
Suggested change
| fragments: | |
| includes: |
emersonknapp
commented
May 28, 2026
| type: string | ||
| description: Human-readable description of what this node does. | ||
|
|
||
| base: |
Member
Author
There was a problem hiding this comment.
required. make node's definition into a fragment? Make the node schema be like:
- base
- my fragment
- included fragments
emersonknapp
commented
May 28, 2026
|
|
||
| description: | ||
| type: string | ||
| description: Human-readable description of what this node does. |
Member
Author
There was a problem hiding this comment.
make description required?
Schema (nodl_schema/schemas/nodl.schema.yaml): Top-level 'base' (enum of node / lifecycle_node) declares the built-in node interface to inherit. Top-level 'fragments' (array of fragment_ref) declares additional fragment interfaces to compose in, by relative path or 'nodl://pkg/name'. fragment_ref definition has required 'ref' and optional 'name' (label used for merge ordering and documentation). Generated models pick these up automatically; FragmentRef and the Base enum are added to NodlDocument. nodl_schema.validator: validate_fragment(data) runs the regular schema validation, then rejects the presence of top-level 'base' or 'fragments'. Fragments are flat ingredients; nested composition is intentionally disallowed in v2 and can be lifted later without a schema change. load_fragment(source) wraps load_nodl with this stricter check. python -m nodl_schema gains a --fragment flag for build-time hooks. nodl_schema.resolve: resolve(doc, source_path=None) returns a LayeredDocument carrying the resolved base, the resolved fragments (by label), and the main document. LayeredDocument.merged() flattens into a single NodlDocument with later layers winning on duplicate names; order is base -> fragments (insertion order) -> main. Every load path goes through load_fragment, so a fragment that declares its own base or fragments is rejected at resolve time with a clear error. Bundled fragments: node.nodl.yaml: declares use_sim_time. lifecycle_node.nodl.yaml: adds the standard transition services and the transition_event publisher on top of the node fragment. ament_nodl_register_fragment: Sibling of register_node, following the same install RENAME pattern, rosidl-style docstring, and "NoDL file" wording. Build-time validation via add_custom_command/target that runs 'python -m nodl_schema --fragment <file>' against the source. The stamp target is ALL, so install won't proceed without it. Tests: test_ament_nodl gains register_fragment tests (5 cases) covering default and explicit PACKAGE, byte-for-byte resource vs source, and source-file install layout. nodl_schema/test/test_resolve.py covers no-base, both bases, relative fragment resolution (success / missing / no source path), layer precedence (main > fragments > base), and explicit rejection of a fragment that declares its own base or fragments. nodl_schema/test/test_schema.py: the previously inverted base/fragments rejection tests become positive accept tests, plus 'unknown base rejected' and 'fragment_ref missing ref rejected' negative cases. nodl_schema/test/test_validator_cli.py: adds --fragment cases for valid fragments, rejection of base/fragments at the top level, and combined invalid-schema + fragment cases. Smoke-tested end-to-end by appending 'base: node' to a fragment fixture: the build fails at the validate_fragment target with the expected error and restoring brings it back green. Signed-off-by: Emerson Knapp <emerson.b.knapp@gmail.com>
emersonknapp
force-pushed
the
emerson/fragments
branch
from
ac271a3 to
a5f8b7d
Compare
Signed-off-by: Emerson Knapp <emerson@polymathrobotics.com>
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 #72
Replaces #76
Adds a new concept of a "NoDL Fragment" that is a partial specification for a node. There are effectively two use cases for framents:
NodeorLifecycleNode) which brings along with it a certain interface setTfBroadcaster(which creates publishers) andTfBuffer(which creates subscriptions). This pattern is also used in Navigation2 to add parameters to nodes, etc.The fragment concept allows resolving a full specification for a node via reference to other sub-documents, while keeping it clear for code generation and documentation what specifically this node code actually provides.