docs: expand website documentation with guides and architecture #633
Conversation
📝 WalkthroughWalkthroughAdds extensive documentation and site navigation: installation, building, architecture, multiple how-to guides (generation, module loading, I/O, Metapath, constraints, schema generation), Claude Code integration, index restructuring, README shell-completion note, and minor CSS/site config updates. No code or public API changes. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/site/site.xml (1)
69-79: Add "Guides" to the navbar and bottomNav filters.The navbar
filterMenu="Documentation|Maven Documentation|modules"uses inclusive regex matching and excludes the newly-added "Guides" menu (lines 118-126). To make "Guides" visible in the top navbar, add it to the filterMenu pattern. Additionally, add "Guides" to one of the bottomNav column regexes (lines 75-79) if it should appear in the footer navigation as well.
🤖 Fix all issues with AI agents
In @src/site/markdown/guides/validating-with-constraints.md.vm:
- Around line 105-196: Update the CustomHandler example to import java.util.List
and java.util.ArrayList, declare or inject a logger field, and replace the
nonexistent Severity enum with IConstraint.Level (from
dev.metaschema.core.model.constraint.IConstraint) when checking severities; in
handleFinding use compareTo(IConstraint.Level.ERROR) (or similar) instead of
ordinal() comparisons for robustness, and ensure the class implements
IConstraintValidationHandler and references IFinding in method signatures
(update imports to include dev.metaschema.core.model.constraint.IConstraint and
dev.metaschema.core.model.constraint.IFinding).
In @src/site/markdown/index.md.vm:
- Line 3: Replace the pages.nist.gov Metaschema URL with the canonical docs URL
by finding the string "https://pages.nist.gov/metaschema/" in the markdown (the
occurrences in index.md.vm) and changing it to
"https://framework.metaschema.dev/"; update both places where that URL appears
so all links point to the canonical documentation.
🧹 Nitpick comments (9)
src/site/markdown/guides/generating-schemas.md.vm (4)
90-105: Add missing imports to the code example.The XML Schema generation example uses
WriterandFilesbut doesn't show their imports. Consider adding:import java.io.Writer; import java.nio.file.Files;📝 Complete the imports
import dev.metaschema.core.model.IModule; import dev.metaschema.core.model.MetaschemaLoader; import dev.metaschema.schemagen.xml.XmlSchemaGenerator; +import java.io.Writer; +import java.nio.file.Files; import java.nio.file.Path;
110-121: Add missing imports to the JSON Schema example.Similar to the XML example, this code uses
WriterandFileswithout showing imports. Adding the imports would make the example more complete for users copying the code.
196-214: Add missing imports to XML validation example.The XML validation example uses several classes without showing their imports. For completeness, add:
import javax.xml.XMLConstants; import javax.xml.transform.stream.StreamSource; import org.xml.sax.SAXException; import java.io.File;
216-238: Complete the JSON validation example with missing context.The JSON validation example references
objectMapper(line 230) andVersionFlagwithout defining them. Consider adding:import com.fasterxml.jackson.databind.ObjectMapper; import com.networknt.schema.SpecVersion.VersionFlag; ObjectMapper objectMapper = new ObjectMapper();src/site/markdown/guides/loading-metaschema-modules.md.vm (3)
156-167: Add missing import for IOException.The error handling example catches
IOExceptionat line 164 but doesn't include the corresponding import statement. For completeness, add:📝 Add missing import
import dev.metaschema.core.model.MetaschemaException; +import java.io.IOException;
80-82: Clarify or demonstrate recursive module traversal.The comment at line 80 suggests "recursive" retrieval of the complete module chain, but the code at line 81 only calls
getImportedModules()again without showing any recursive traversal logic. Either clarify that the method itself returns all modules recursively, or provide an example that demonstrates how to recursively traverse the import hierarchy.
206-218: Add missing import for INamedModelDefinition.The utility method uses
INamedModelDefinitionas the return type at line 209, but the corresponding import statement is not shown. For completeness, add:import dev.metaschema.core.model.INamedModelDefinition;src/site/markdown/guides/reading-writing-data.md.vm (1)
240-272: Add missing import for Stream.The batch processing example uses
Stream<Path>at line 248 but doesn't include the corresponding import statement. Add the missing import for completeness:import java.util.stream.Stream;src/site/markdown/guides/executing-metapath.md.vm (1)
214-235: Add missing imports for MetapathCache example.The
MetapathCacheutility class usesMapandConcurrentHashMapat lines 218-219 but doesn't include the corresponding import statements. For completeness, add:import java.util.Map; import java.util.concurrent.ConcurrentHashMap;
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
README.mdsrc/site/markdown/building.md.vmsrc/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/guides/executing-metapath.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vmsrc/site/markdown/index.md.vmsrc/site/markdown/installation.md.vmsrc/site/resources/css/custom.csssrc/site/site.xml
🧰 Additional context used
🧠 Learnings (20)
📓 Common learnings
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 0
File: :0-0
Timestamp: 2026-01-05T16:33:59.206Z
Learning: In metaschema-framework/metaschema-java, the core/metaschema submodule is owned by this project's maintainers; updates to it are coordinated within this repository, so no follow-up issues should be opened in external repositories for submodule changes.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 550
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/format/JsonPointerFormatter.java:56-100
Timestamp: 2025-12-19T04:01:45.001Z
Learning: In Java code for metaschema-framework/metaschema-java, override methods (annotated with Override) that implement interface methods automatically inherit Javadoc from the interface and do not require redundant documentation in the implementing class unless there is implementation-specific behavior that needs to be documented beyond what the interface specifies.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: When adding or modifying datatypes, update `schema/json/metaschema-datatypes.json`, `schema/xml/metaschema-datatypes.xsd`, and `website/content/specification/datatypes.md` in sync
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
README.mdsrc/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/building.md.vmsrc/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/executing-metapath.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vmsrc/site/site.xmlsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-30T19:08:21.896Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Applied to files:
README.mdsrc/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/building.md.vmsrc/site/site.xmlsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2026-01-05T16:33:59.206Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 0
File: :0-0
Timestamp: 2026-01-05T16:33:59.206Z
Learning: In metaschema-framework/metaschema-java, the core/metaschema submodule is owned by this project's maintainers; updates to it are coordinated within this repository, so no follow-up issues should be opened in external repositories for submodule changes.
Applied to files:
README.mdsrc/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/building.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-30T04:19:49.192Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Applied to files:
src/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/building.md.vmsrc/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-24T21:22:07.082Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Applied to files:
src/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/building.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-24T21:21:56.361Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Applied to files:
src/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/building.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: When adding or modifying datatypes, update `schema/json/metaschema-datatypes.json`, `schema/xml/metaschema-datatypes.xsd`, and `website/content/specification/datatypes.md` in sync
Applied to files:
src/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vm
📚 Learning: 2025-12-24T21:21:40.208Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Applied to files:
src/site/markdown/guides/loading-metaschema-modules.md.vmsrc/site/markdown/building.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2026-01-05T16:08:37.155Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).
Applied to files:
src/site/markdown/building.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to core/src/main/antlr4/** : Metapath parser is generated from ANTLR4 grammar files in core/src/main/antlr4. Code generation occurs during Maven build producing output in target/generated-sources/
Applied to files:
src/site/markdown/building.md.vmsrc/site/markdown/guides/executing-metapath.md.vmsrc/site/markdown/guides/generating-java-classes.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to core/metaschema/schema/xml/** : XMLBeans code is generated from XSD schemas in core/metaschema/schema/xml during Maven build. Generated sources are placed in target/generated-sources/
Applied to files:
src/site/markdown/building.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. Use the XPath 3.1 specification (https://www.w3.org/TR/xpath-31/) and XPath Functions 3.1 (https://www.w3.org/TR/xpath-functions-31/) as authoritative reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
Applied to files:
src/site/markdown/guides/executing-metapath.md.vm
📚 Learning: 2025-01-07T00:50:46.218Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/type/InstanceOf.java:87-88
Timestamp: 2025-01-07T00:50:46.218Z
Learning: In the Metapath implementation, child expressions should be called using `accept()` rather than `evaluate()` to ensure proper management of the execution stack through push/pop operations. The `evaluate()` method is an internal implementation detail that performs the actual evaluation.
Applied to files:
src/site/markdown/guides/executing-metapath.md.vm
📚 Learning: 2025-01-07T00:51:17.257Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/ArraySequenceConstructor.java:63-63
Timestamp: 2025-01-07T00:51:17.257Z
Learning: In the Metapath implementation, expression evaluation must go through the `accept()` method rather than calling `evaluate()` directly, as `accept()` handles the push/pop operations on the execution stack which is used for debugging and error reporting.
Applied to files:
src/site/markdown/guides/executing-metapath.md.vm
📚 Learning: 2025-12-19T04:01:45.001Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 550
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/format/JsonPointerFormatter.java:56-100
Timestamp: 2025-12-19T04:01:45.001Z
Learning: In Java code for metaschema-framework/metaschema-java, override methods (annotated with Override) that implement interface methods automatically inherit Javadoc from the interface and do not require redundant documentation in the implementing class unless there is implementation-specific behavior that needs to be documented beyond what the interface specifies.
Applied to files:
src/site/markdown/guides/generating-java-classes.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.{xmlbeans,antlr} : Generated code in *.xmlbeans and *.antlr packages is excluded from Javadoc and style checks. Generated sources are placed in target/generated-sources/
Applied to files:
src/site/markdown/guides/generating-java-classes.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Constraints are documented in `website/content/specification/syntax/constraints.md`. When adding new constraint types, update the constraint type lists for `define-flag`, `define-field`, and `define-assembly`, and add a new section with syntax table and examples
Applied to files:
src/site/markdown/guides/validating-with-constraints.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Keep `schema/json/`, `schema/xml/`, and `website/content/specification/datatypes.md` in sync when updating schema definitions
Applied to files:
src/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: The data type documentation in `website/content/specification/datatypes.md` must stay in sync with schema definitions in `schema/json/metaschema-datatypes.json` and `schema/xml/metaschema-datatypes.xsd`
Applied to files:
src/site/markdown/guides/generating-schemas.md.vmsrc/site/markdown/guides/reading-writing-data.md.vm
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Website
- GitHub Check: Code
🔇 Additional comments (12)
README.md (1)
120-150: Shell completion documentation looks comprehensive.The instructions for both Bash and Zsh are clear and follow standard completion setup patterns. The temporary vs. persistent setup distinction is helpful for users.
src/site/resources/css/custom.css (2)
24-29: Table header alignment fix is well-documented.The CSS override correctly addresses the Flexmark limitation by forcing left alignment on table headers. The comment clearly explains why this workaround is needed.
20-22: No changes needed. The CSS syntax is valid. Line 22 contains the proper closing brace for thecodeselector block that opens on line 20, following standard CSS structure (selector { property: value; }). There is no syntax error or extraneous brace.src/site/markdown/installation.md.vm (3)
29-29: No issues found. The link tobuilding.htmlin line 29 is correct—building.md.vmexists in the site structure and Maven site plugin will generatebuilding.htmlfrom it.
162-165: All guide files referenced in lines 162-165 exist in the repository and will generate the expected HTML files during the Maven site build process. No action required.
127-137: No issues found with external IDE documentation links.All three links in the IDE setup section are valid and point to current official documentation: IntelliJ IDEA Maven support, Eclipse M2Eclipse, and VS Code Java Extension Pack are all actively maintained by their respective publishers and accessible.
src/site/markdown/guides/architecture.md.vm (2)
43-55: All core interfaces listed in the architecture guide exist in the codebase and are correctly named. No issues identified.
344-350: The Related Projects section references are correct. All three GitHub repositories exist and are properly maintained within the metaschema-framework organization:
- liboscal-java is a Java library for processing OSCAL content
- oscal-cli is a command-line tool for working with OSCAL and Metaschema
- metaschema hosts the Metaschema specification
No changes needed.
src/site/markdown/guides/generating-schemas.md.vm (1)
16-57: Update Maven plugin goal names and configuration.The goals
generate-xsdandgenerate-json-schemado not exist. The correct goal isgenerate-schemas, which supports both XML and JSON schema generation via aformatsparameter. Use separate executions with the same goal but differentformatvalues:Corrected configuration
<build> <plugins> <plugin> <groupId>dev.metaschema.java</groupId> <artifactId>metaschema-maven-plugin</artifactId> <version>${project.version}</version> <executions> <!-- Generate XML Schema --> <execution> <id>generate-xsd</id> <goals> <goal>generate-schemas</goal> </goals> <configuration> <metaschemaDir>src/main/metaschema</metaschemaDir> <includes> <include>my-model_metaschema.xml</include> </includes> <outputDirectory>${project.build.directory}/schemas/xsd</outputDirectory> <formats> <format>xsd</format> </formats> </configuration> </execution> <!-- Generate JSON Schema --> <execution> <id>generate-json-schema</id> <goals> <goal>generate-schemas</goal> </goals> <configuration> <metaschemaDir>src/main/metaschema</metaschemaDir> <includes> <include>my-model_metaschema.xml</include> </includes> <outputDirectory>${project.build.directory}/schemas/json</outputDirectory> <formats> <format>json</format> </formats> </configuration> </execution> </executions> </plugin> </plugins> </build>⛔ Skipped due to learnings
Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 567 File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47 Timestamp: 2025-12-24T21:21:56.361Z Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 567 File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80 Timestamp: 2025-12-24T21:22:07.082Z Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 567 File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47 Timestamp: 2025-12-24T21:21:40.208Z Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 605 File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484 Timestamp: 2025-12-30T04:19:49.192Z Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.Learnt from: CR Repo: metaschema-framework/metaschema-java PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-12-17T13:27:43.679Z Learning: Applies to core/metaschema/schema/xml/** : XMLBeans code is generated from XSD schemas in core/metaschema/schema/xml during Maven build. Generated sources are placed in target/generated-sources/Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 618 File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52 Timestamp: 2026-01-05T18:03:33.537Z Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).Learnt from: CR Repo: metaschema-framework/metaschema-java PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-12-17T13:27:43.679Z Learning: Applies to core/src/main/antlr4/** : Metapath parser is generated from ANTLR4 grammar files in core/src/main/antlr4. Code generation occurs during Maven build producing output in target/generated-sources/src/site/markdown/claude-integration.md.vm (1)
106-112: Verify documentation URL preference for specification links.Lines 111-112 use
https://pages.nist.gov/metaschema/URLs for the specification and Metapath reference. Based on learnings,https://framework.metaschema.dev/is the project's preferred canonical documentation URL. Please verify whether the specification content is available at framework.metaschema.dev or if pages.nist.gov is intentionally used for specification pages specifically.Based on learnings, the project uses framework.metaschema.dev as the official reference.
src/site/markdown/guides/loading-metaschema-modules.md.vm (1)
108-115: The API methodgetJavaTypeAdapter()is the correct and only method available for retrieving field data type information. This method is declared in theIValuedDefinitioninterface (whichIFieldDefinitionextends) with documentation stating "Retrieves the data type of the definition's value." The suggested alternatives (getDataType(),getValueType(),getDataTypeAdapter()) do not exist in the public API. The method name includes "Java" because it returns anIDataTypeAdapterobject, which is the framework's mechanism for working with typed values.src/site/markdown/guides/validating-with-constraints.md.vm (1)
16-91: Both<index>and<is-unique>are supported constraint types that serve different purposes and can coexist in the same schema. The<index>constraint creates a named index for cross-reference validation (used with<index-has-key>), while<is-unique>ensures uniqueness without persisting a named index. The guide appropriately shows both, though it could benefit from clarifying their distinct use cases.Likely an incorrect or invalid review comment.
- Add installation.md.vm with Maven/Gradle dependencies and snapshots - Add building.md.vm with JDK 17 requirement and CI profile instructions - Add claude-integration.md.vm documenting Claude Code plugin skills - Add 7 guide pages covering module loading, code generation, data binding, Metapath queries, constraint validation, schema generation, and architecture - Update site.xml with Documentation and Guides navigation menus - Enhance index.md.vm with quick start and feature overview
david-waltermire
force-pushed
the
site-expansion
branch
from
0278663 to
9fe0969
Compare
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Fix all issues with AI agents
In @src/site/markdown/guides/generating-schemas.md.vm:
- Around line 198-214: The example uses XMLConstants in the
SchemaFactory.newInstance call but doesn't import it, causing a compilation
error; add the missing import for javax.xml.XMLConstants alongside the other
imports in the snippet so XMLConstants is resolved (leave the rest of the
example unchanged and keep imports grouped with Schema, SchemaFactory,
Validator).
- Around line 90-106: The example is missing imports for Writer and Files;
update the imports at the top of the snippet to include java.io.Writer and
java.nio.file.Files so the programmatic XSD generation code (classes
MetaschemaLoader, IModule, XmlSchemaGenerator and the try-with-resources using
Writer and Files.newBufferedWriter) compiles and runs.
- Around line 110-121: Add the missing Java imports and declare/initialize the
loader used in the snippet: import java.io.Writer, import java.nio.file.Files
and import java.nio.file.Path at the top of the example, and add a
declaration/initialization for the loader variable (the same loader type and
setup used in the XSD example) before calling loader.load so that IModule module
= loader.load(Path.of(...)) compiles; keep the existing IModule and
JsonSchemaGenerator usage unchanged.
- Around line 220-238: The Maven dependency example for
com.networknt:json-schema-validator in the guide is outdated; update the
suggested dependency block to use version 3.0.0 by replacing the version value
with 3.0.0 for the artifact com.networknt:json-schema-validator and insert that
dependency XML snippet just before the Java example (the code block that
declares JsonSchemaFactory, JsonSchema, ValidationMessage, etc.) so readers see
the correct dependency to compile the shown classes.
In @src/site/markdown/guides/validating-with-constraints.md.vm:
- Around line 173-203: The example wrongly implements a non-existent
handleFinding(IFinding) and uses IFinding; replace this with implementations of
the actual IConstraintValidationHandler methods (e.g.,
handleCardinalityMinimumViolation(...), handleIndexDuplicateKeyViolation(...),
and the other interface methods declared on IConstraintValidationHandler) and
collect/record the provided parameters (severity/message/location) instead of
IFinding; update uses of Level and logging to extract severity and message from
the concrete handler method arguments so the class implements the real interface
signatures and compiles.
- Around line 141-169: The switch over finding.getSeverity()
(IValidationFinding.getSeverity(), which returns IConstraint.Level) only handles
CRITICAL, ERROR, WARNING and INFORMATIONAL; update the switch in the loop over
result.getFindings() to handle all enum values by adding cases for DEBUG and
NONE (e.g., call logDebug(finding) for DEBUG and no-op or comment for NONE) or
add a default case that properly handles unexpected levels so all enum constants
are covered.
- Around line 109-122: The example calls a nonexistent method
setConstraintValidationEnabled on IDeserializer; replace that call with the
feature-based API by invoking
deserializer.enableFeature(DeserializationFeature.DESERIALIZE_VALIDATE_CONSTRAINTS)
after creating the IDeserializer from
IBindingContext.instance().newDeserializer(Format.JSON, MyModel.class) so
constraint validation is enabled correctly.
🧹 Nitpick comments (2)
src/site/resources/css/custom.css (1)
20-29: Scope thetable thalignment override (current selector is very global).
.table th, table th { text-align: left !important; }is likely to affect every table header in the site (including non-doc tables) and will prevent any intentional right/center header alignment from taking effect.
- Consider scoping this to the documentation content container (whatever the skin uses) and/or dropping
!importantif a more specific selector is enough.- At minimum, please verify a page with centered/right-aligned columns to ensure the override doesn’t regress layout. (This aligns with your pending “verify rendered pages display correctly”.)
src/site/markdown/index.md.vm (1)
29-75: Maven snippets may render*-SNAPSHOT; add a quick note to prevent copy/paste failures.If this site is built from
develop,${project.version}will typically be a snapshot, which won’t work for most users unless they add snapshot repo instructions. Consider adding a 1–2 line note right above the dependency/plugin snippets.Proposed doc tweak
## Quick Start Add the dependency to your Maven project: +> Note: If this site is built from a `*-SNAPSHOT` version, use the latest release version instead (or configure your build to consume snapshots). + ```xml <dependency> <groupId>${project.groupId}</groupId> <artifactId>metaschema-databind</artifactId> <version>${project.version}</version> </dependency></details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 027866356720d4ceb758bae9f6468435e0140519 and 9fe0969cd1581a5021451149a6b30221e96a4644. </details> <details> <summary>📒 Files selected for processing (14)</summary> * `README.md` * `src/site/markdown/building.md.vm` * `src/site/markdown/claude-integration.md.vm` * `src/site/markdown/guides/architecture.md.vm` * `src/site/markdown/guides/executing-metapath.md.vm` * `src/site/markdown/guides/generating-java-classes.md.vm` * `src/site/markdown/guides/generating-schemas.md.vm` * `src/site/markdown/guides/loading-metaschema-modules.md.vm` * `src/site/markdown/guides/reading-writing-data.md.vm` * `src/site/markdown/guides/validating-with-constraints.md.vm` * `src/site/markdown/index.md.vm` * `src/site/markdown/installation.md.vm` * `src/site/resources/css/custom.css` * `src/site/site.xml` </details> <details> <summary>✅ Files skipped from review due to trivial changes (3)</summary> * README.md * src/site/markdown/guides/loading-metaschema-modules.md.vm * src/site/markdown/guides/reading-writing-data.md.vm </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (7)</summary> * src/site/site.xml * src/site/markdown/guides/executing-metapath.md.vm * src/site/markdown/installation.md.vm * src/site/markdown/guides/architecture.md.vm * src/site/markdown/building.md.vm * src/site/markdown/guides/generating-java-classes.md.vm * src/site/markdown/claude-integration.md.vm </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (17)</summary> <details> <summary>📓 Common learnings</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 0
File: :0-0
Timestamp: 2026-01-05T16:33:59.206Z
Learning: In metaschema-framework/metaschema-java, the core/metaschema submodule is owned by this project's maintainers; updates to it are coordinated within this repository, so no follow-up issues should be opened in external repositories for submodule changes.Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 550
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/format/JsonPointerFormatter.java:56-100
Timestamp: 2025-12-19T04:01:45.001Z
Learning: In Java code for metaschema-framework/metaschema-java, override methods (annotated with Override) that implement interface methods automatically inherit Javadoc from the interface and do not require redundant documentation in the implementing class unless there is implementation-specific behavior that needs to be documented beyond what the interface specifies.Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: When adding or modifying datatypes, updateschema/json/metaschema-datatypes.json,schema/xml/metaschema-datatypes.xsd, andwebsite/content/specification/datatypes.mdin sync</details> <details> <summary>📚 Learning: 2026-01-05T18:03:33.537Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` - `src/site/markdown/guides/validating-with-constraints.md.vm` </details> <details> <summary>📚 Learning: 2026-01-05T16:33:59.206Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 0
File: :0-0
Timestamp: 2026-01-05T16:33:59.206Z
Learning: In metaschema-framework/metaschema-java, the core/metaschema submodule is owned by this project's maintainers; updates to it are coordinated within this repository, so no follow-up issues should be opened in external repositories for submodule changes.**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` </details> <details> <summary>📚 Learning: 2025-12-30T19:08:21.896Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` </details> <details> <summary>📚 Learning: 2025-12-24T21:22:07.082Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` - `src/site/markdown/guides/validating-with-constraints.md.vm` </details> <details> <summary>📚 Learning: 2025-12-24T21:21:56.361Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` </details> <details> <summary>📚 Learning: 2026-01-05T16:08:37.155Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).**Applied to files:** - `src/site/markdown/index.md.vm` </details> <details> <summary>📚 Learning: 2025-12-30T04:19:49.192Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` - `src/site/markdown/guides/validating-with-constraints.md.vm` </details> <details> <summary>📚 Learning: 2025-12-24T21:21:40.208Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` </details> <details> <summary>📚 Learning: 2024-11-14T17:07:03.586Z</summary>Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 245
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/item/atomic/IIPv4AddressItem.java:66-73
Timestamp: 2024-11-14T17:07:03.586Z
Learning: In the Metaschema Java codebase, differences in casting patterns across atomic type implementations are intentional and required; any differences in approach are significant and necessary.**Applied to files:** - `src/site/markdown/index.md.vm` </details> <details> <summary>📚 Learning: 2025-12-13T21:16:12.281Z</summary>Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Use semantic versioning. Version must be tracked inpackage.jsonandschema/metaschema/metaschema-module-metaschema.xml**Applied to files:** - `src/site/markdown/index.md.vm` </details> <details> <summary>📚 Learning: 2025-12-13T21:16:12.281Z</summary>Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Deprecated features in specification documentation should show only non-deprecated values in the syntax overview (_index.md), but document deprecated values with clear notices in detailed documentation pages**Applied to files:** - `src/site/markdown/index.md.vm` </details> <details> <summary>📚 Learning: 2025-12-13T21:16:12.281Z</summary>Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Use RFC 2119 keywords (MUST, SHOULD, MAY) consistently in uppercase in specification documentation**Applied to files:** - `src/site/markdown/index.md.vm` </details> <details> <summary>📚 Learning: 2025-12-17T13:27:43.679Z</summary>Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to core/metaschema/schema/xml/** : XMLBeans code is generated from XSD schemas in core/metaschema/schema/xml during Maven build. Generated sources are placed in target/generated-sources/**Applied to files:** - `src/site/markdown/index.md.vm` - `src/site/markdown/guides/generating-schemas.md.vm` </details> <details> <summary>📚 Learning: 2025-12-13T21:16:12.281Z</summary>Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Keepschema/json/,schema/xml/, andwebsite/content/specification/datatypes.mdin sync when updating schema definitions**Applied to files:** - `src/site/markdown/guides/generating-schemas.md.vm` </details> <details> <summary>📚 Learning: 2025-12-13T21:16:12.281Z</summary>Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: When adding or modifying datatypes, updateschema/json/metaschema-datatypes.json,schema/xml/metaschema-datatypes.xsd, andwebsite/content/specification/datatypes.mdin sync**Applied to files:** - `src/site/markdown/guides/generating-schemas.md.vm` </details> <details> <summary>📚 Learning: 2025-12-13T21:16:12.281Z</summary>Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Constraints are documented inwebsite/content/specification/syntax/constraints.md. When adding new constraint types, update the constraint type lists fordefine-flag,define-field, anddefine-assembly, and add a new section with syntax table and examples**Applied to files:** - `src/site/markdown/guides/validating-with-constraints.md.vm` </details> </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)</summary> * GitHub Check: Code * GitHub Check: Website </details> <details> <summary>🔇 Additional comments (7)</summary><blockquote> <details> <summary>src/site/markdown/guides/validating-with-constraints.md.vm (3)</summary><blockquote> `1-317`: **Overall: Well-structured and comprehensive guide.** The document provides excellent coverage of constraint validation with clear examples for both XML constraint definitions and Java validation code. The progression from basic constraint types through to custom handlers and best practices is logical and helpful. --- `126-137`: **Verify `IValidationResult` API and method names.** The method names are correct: `isPassing()`, `getFindings()`, `getLocation()`, `getMessage()`, and `getSeverity()` are all confirmed in the API. However, the example call `context.validate(model)` is incomplete. The actual validate methods on `IBindingContext` require additional parameters such as `IBoundLoader`, `IConfiguration<ValidationFeature<?>>`, `Format`, and/or `ISchemaValidationProvider` depending on the validation scenario. The example should be updated to show the correct method signature with all required parameters. --- `222-241`: **Correct the external constraints XML syntax; the example uses non-existent elements.** The example shows `<import-constraints>` in the metaschema element and `<constraints>` as a root element, neither of which exist in the Metaschema specification. The correct syntax uses `<metaschema-meta-constraints>` as the root element for external constraint files and `<import>` (not `<import-constraints>`) to reference other constraint files. <details> <summary>Corrected example</summary> ```xml <!-- main-module.xml --> <metaschema> <!-- External constraints are loaded separately, not imported here --> </metaschema> <!-- additional-constraints.xml --> <metaschema-meta-constraints xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"> <import href="other-constraints.xml" /> <context> <metapath target="/catalog//control</metapath> <constraints> <expect target="./title" test="exists(.)" message="Controls must have titles" /> </constraints> </context> </metaschema-meta-constraints>External constraint files are loaded programmatically via
IConstraintLoader, not declared in the metaschema module.⛔ Skipped due to learnings
Learnt from: CR Repo: metaschema-framework/metaschema PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-12-13T21:16:12.281Z Learning: Constraints are documented in `website/content/specification/syntax/constraints.md`. When adding new constraint types, update the constraint type lists for `define-flag`, `define-field`, and `define-assembly`, and add a new section with syntax table and examplessrc/site/markdown/guides/generating-schemas.md.vm (1)
308-314: All referenced guide files exist insrc/site/markdown/guides/, so the cross-reference links are accurate and will resolve correctly:architecture.md.vm,loading-metaschema-modules.md.vm, andvalidating-with-constraints.md.vmare all present in the same directory.Likely an incorrect or invalid review comment.
src/site/markdown/index.md.vm (3)
3-13: Good: uses canonical docs URL + correctdev.metaschema.*package naming.Line 3 points to
https://framework.metaschema.dev/(preferred canonical URL), and the Java snippet usesdev.metaschema.*(current package convention).
77-139: All internal site links resolve correctly.Verification confirms all referenced markdown sources exist in the repository:
- Root pages:
installation.md.vm,building.md.vm,claude-integration.md.vm- Guides:
generating-java-classes,loading-metaschema-modules,reading-writing-data,executing-metapath,validating-with-constraints,generating-schemasNo broken links detected. The Maven build will process these
.md.vmtemplates into.htmlfiles during the site generation phase.
41-58: The Java code snippet is accurate and matches the current Metaschema framework APIs. TheIBindingContext.instance()factory method is correct, theFormat.JSONandFormat.XMLconstants are valid, and the method signatures fornewDeserializer(Format format, Class<T> clazz)andnewSerializer(Format format, Class<T> clazz)are correct. The imports and usage patterns in the snippet are consistent with the official Metaschema Java databind API documentation.
| ```java | ||
| import com.networknt.schema.JsonSchemaFactory; | ||
| import com.networknt.schema.JsonSchema; | ||
| import com.networknt.schema.ValidationMessage; | ||
|
|
||
| JsonSchemaFactory factory = JsonSchemaFactory.getInstance( | ||
| VersionFlag.V7); | ||
| JsonSchema schema = factory.getSchema( | ||
| new FileInputStream("output.json")); | ||
|
|
||
| JsonNode document = objectMapper.readTree(new File("document.json")); | ||
| Set<ValidationMessage> errors = schema.validate(document); | ||
|
|
||
| if (errors.isEmpty()) { | ||
| System.out.println("Valid!"); | ||
| } else { | ||
| errors.forEach(err -> System.err.println(err.getMessage())); | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
networknt json-schema-validator latest version maven central
💡 Result:
Latest on Maven Central: com.networknt:json-schema-validator version 3.0.0. [1][2]
Maven dependency:
com.networknt
json-schema-validator
3.0.0
Sources: Maven Central listing (artifact directory) and project README. [1][2]
References:
[1] Maven Central — com/networknt/json-schema-validator.
[2] networknt/json-schema-validator README (GitHub).
Update the suggested Maven dependency to the latest version.
The suggestion to add the networknt/json-schema-validator dependency note is helpful for documentation. However, the proposed version (1.0.87) is significantly outdated. Update it to the current latest version on Maven Central: 3.0.0.
📝 Suggested addition before line 220
### JSON Validation
Using a JSON Schema validator library:
+
+> **Note:** Add the `networknt/json-schema-validator` dependency to your project:
+> ```xml
+> <dependency>
+> <groupId>com.networknt</groupId>
+> <artifactId>json-schema-validator</artifactId>
+> <version>3.0.0</version>
+> </dependency>
+> ```🤖 Prompt for AI Agents
In @src/site/markdown/guides/generating-schemas.md.vm around lines 220 - 238,
The Maven dependency example for com.networknt:json-schema-validator in the
guide is outdated; update the suggested dependency block to use version 3.0.0 by
replacing the version value with 3.0.0 for the artifact
com.networknt:json-schema-validator and insert that dependency XML snippet just
before the Java example (the code block that declares JsonSchemaFactory,
JsonSchema, ValidationMessage, etc.) so readers see the correct dependency to
compile the shown classes.
There was a problem hiding this comment.
@coderabbitai Thank you for the version update suggestion. The documentation example uses a placeholder version - users should always check Maven Central for the latest version when implementing.
There was a problem hiding this comment.
@david-waltermire, understood! That makes sense — using placeholder versions encourages users to verify they're using the most current dependency rather than copying an example that may become outdated. I appreciate the clarification on the documentation philosophy.
✏️ Learnings added
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 633
File: src/site/markdown/guides/generating-schemas.md.vm:235-260
Timestamp: 2026-01-11T15:17:25.994Z
Learning: In metaschema-framework/metaschema-java documentation, david-waltermire prefers using placeholder versions for third-party library dependencies in code examples rather than hardcoding specific versions, so users are encouraged to check Maven Central for the latest version when implementing.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to core/metaschema/schema/xml/** : XMLBeans code is generated from XSD schemas in core/metaschema/schema/xml during Maven build. Generated sources are placed in target/generated-sources/
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Keep `schema/json/`, `schema/xml/`, and `website/content/specification/datatypes.md` in sync when updating schema definitions
- Use canonical URL framework.metaschema.dev instead of pages.nist.gov - Fix @nonnull placement claim (on getter/setter, not field) - Remove non-existent builder pattern example - Fix Severity enum to IConstraint.Level in CustomHandler example - Fix shell-completion to generate-completion in README
david-waltermire
force-pushed
the
site-expansion
branch
from
9fe0969 to
0d78946
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @src/site/markdown/index.md.vm:
- Line 3: The "Claude Code" link (https://claude.ai/code) in the Claude Code
section is inaccessible (HTTP 403); either correct the URL to the proper public
Claude Code page or remove/replace the link with an accessible resource. Locate
the Claude Code section in src/site/markdown/index.md.vm, update the anchor URL
text to a verified reachable Claude Code page (or replace with an alternative
tool's link), and ensure the link renders and returns HTTP 200 when tested.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
README.mdsrc/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/generating-java-classes.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vmsrc/site/markdown/index.md.vm
✅ Files skipped from review due to trivial changes (1)
- src/site/markdown/guides/validating-with-constraints.md.vm
🚧 Files skipped from review as they are similar to previous changes (3)
- README.md
- src/site/markdown/claude-integration.md.vm
- src/site/markdown/guides/generating-java-classes.md.vm
🧰 Additional context used
🧠 Learnings (13)
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-30T19:08:21.896Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-24T21:22:07.082Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2026-01-05T16:33:59.206Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 0
File: :0-0
Timestamp: 2026-01-05T16:33:59.206Z
Learning: In metaschema-framework/metaschema-java, the core/metaschema submodule is owned by this project's maintainers; updates to it are coordinated within this repository, so no follow-up issues should be opened in external repositories for submodule changes.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-24T21:21:56.361Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-30T04:19:49.192Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-24T21:21:40.208Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2026-01-05T16:08:37.155Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-19T04:01:45.001Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 550
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/format/JsonPointerFormatter.java:56-100
Timestamp: 2025-12-19T04:01:45.001Z
Learning: In Java code for metaschema-framework/metaschema-java, override methods (annotated with Override) that implement interface methods automatically inherit Javadoc from the interface and do not require redundant documentation in the implementing class unless there is implementation-specific behavior that needs to be documented beyond what the interface specifies.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Deprecated features in specification documentation should show only non-deprecated values in the syntax overview (`_index.md`), but document deprecated values with clear notices in detailed documentation pages
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: The data type documentation in `website/content/specification/datatypes.md` must stay in sync with schema definitions in `schema/json/metaschema-datatypes.json` and `schema/xml/metaschema-datatypes.xsd`
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2026-01-05T18:03:23.064Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/metapath/format/IPathSegment.java:0-0
Timestamp: 2026-01-05T18:03:23.064Z
Learning: In metaschema-framework/metaschema-java, avoid duplicating SpotBugs nullability annotations on overrides when the superinterface (e.g., dev.metaschema.core.model.IMetapathQueryable#getNodeItem()) already declares the null contract; rely on the inherited annotation instead.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to core/metaschema/schema/xml/** : XMLBeans code is generated from XSD schemas in core/metaschema/schema/xml during Maven build. Generated sources are placed in target/generated-sources/
Applied to files:
src/site/markdown/index.md.vm
🔇 Additional comments (2)
src/site/markdown/index.md.vm (2)
1-140: Excellent documentation restructure!The homepage transformation is well-executed with a clear narrative flow from introduction → target audience → quick start → detailed guides. The code examples are syntactically correct and use the canonical
dev.metaschema.*package naming. The Maven configuration appropriately uses Velocity variables for the.vmtemplate. The progression through sections provides a solid foundation for both new users and those seeking specific functionality.
77-77: All internal documentation links verified successfully. All referenced files exist in the PR structure:
- Single-page docs:
installation.md,building.md,claude-integration.md✓- Guide pages: All 6 guides present ✓
- Module directories: All 5 modules present ✓
| # Metaschema Java Tools | ||
|
|
||
| This project provides a Java implementation of the [Metaschema](https://framework.metaschema.dev/) framework that supports format-agnostic information modeling and processing. A set of tools and libraries are provided that allow developers to quickly develop applications using Metaschema-based models. | ||
| This project provides a Java implementation of the [Metaschema](https://framework.metaschema.dev/) framework, a modeling language designed to enable format-agnostic information modeling and processing. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify external URLs are accessible
urls=(
"https://framework.metaschema.dev/"
"https://www.nist.gov/"
"https://pages.nist.gov/OSCAL/"
"https://github.com/metaschema-framework/liboscal-java"
"https://github.com/metaschema-framework/oscal-cli"
"https://claude.ai/code"
)
for url in "${urls[@]}"; do
status=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 10 "$url" 2>/dev/null)
if [[ "$status" == "200" ]]; then
echo "✓ $url (HTTP 200)"
else
echo "✗ $url (HTTP $status)"
fi
doneRepository: metaschema-framework/metaschema-java
Length of output: 370
🏁 Script executed:
#!/bin/bash
# Check if claude.ai/code is in the file
rg "claude\.ai" src/site/markdown/index.md.vm -A 2 -B 2Repository: metaschema-framework/metaschema-java
Length of output: 301
Claude Code documentation link is inaccessible.
The URL https://claude.ai/code referenced in the Claude Code section returns HTTP 403 (Forbidden) and is not accessible. Verify if this URL is correct or if it should be updated. All other external links are accessible (framework.metaschema.dev, NIST URLs, and GitHub repositories).
🤖 Prompt for AI Agents
In @src/site/markdown/index.md.vm at line 3, The "Claude Code" link
(https://claude.ai/code) in the Claude Code section is inaccessible (HTTP 403);
either correct the URL to the proper public Claude Code page or remove/replace
the link with an accessible resource. Locate the Claude Code section in
src/site/markdown/index.md.vm, update the anchor URL text to a verified
reachable Claude Code page (or replace with an alternative tool's link), and
ensure the link renders and returns HTTP 200 when tested.
There was a problem hiding this comment.
@coderabbitai Thank you for verifying the external URLs. All links are intentional and point to the correct resources.
There was a problem hiding this comment.
@david-waltermire, thank you for the clarification! I understand that the claude.ai/code URL is intentional and correct despite the HTTP 403 response. I've noted this for future reference.
🧠 Learnings used
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 0
File: :0-0
Timestamp: 2026-01-05T16:33:59.206Z
Learning: In metaschema-framework/metaschema-java, the core/metaschema submodule is owned by this project's maintainers; updates to it are coordinated within this repository, so no follow-up issues should be opened in external repositories for submodule changes.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 550
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/format/JsonPointerFormatter.java:56-100
Timestamp: 2025-12-19T04:01:45.001Z
Learning: In Java code for metaschema-framework/metaschema-java, override methods (annotated with Override) that implement interface methods automatically inherit Javadoc from the interface and do not require redundant documentation in the implementing class unless there is implementation-specific behavior that needs to be documented beyond what the interface specifies.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 245
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/item/atomic/IIPv4AddressItem.java:66-73
Timestamp: 2024-11-14T17:07:03.586Z
Learning: In the Metaschema Java codebase, differences in casting patterns across atomic type implementations are intentional and required; any differences in approach are significant and necessary.
aj-stein
left a comment
aj-stein
left a comment
There was a problem hiding this comment.
Much like the other PRs excellent work!
- validating-with-constraints.md.vm: Fixed incorrect API examples - Replaced non-existent setConstraintValidationEnabled with correct API - Updated to use IBoundLoader.enableFeature() and validateWithConstraints() - Replaced custom handler example with FindingCollectingConstraintValidationHandler - generating-schemas.md.vm: Already fixed (previous session) - Added Writer, Files, Path imports to XSD generation - Added imports to JSON Schema generation - Added XMLConstants, StreamSource, File, SAXException to XML validation - Added complete imports to JSON validation - loading-metaschema-modules.md.vm: Added missing imports - Added IOException and Path imports to error handling example - Added INamedModelDefinition, IAssemblyDefinition, IFieldDefinition imports - reading-writing-data.md.vm: Added missing imports - Added Stream, Files, Path imports to batch processing example - Fixed DefaultBindingContext() to IBindingContext.newInstance() - executing-metapath.md.vm: Added missing imports - Added Map, ConcurrentHashMap imports to MetapathCache example
Addressed all code example issuesThe following fixes have been applied in commit d3b9009: validating-with-constraints.md.vm
generating-schemas.md.vm
loading-metaschema-modules.md.vm
reading-writing-data.md.vm
executing-metapath.md.vm
Same fixes applied to liboscal-java PR #237 in commit 7109d39. |
david-waltermire
merged commit 579c6bb
into
metaschema-framework:develop
2 participants
Summary
Test plan
mvn sitebuilds without errorsSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.