Add LogVault audit event schema #5194
Conversation
|
Thanks for the PR! This section of the codebase is owned by @madskristensen and |
There was a problem hiding this comment.
Pull request overview
This PR adds a new JSON schema for LogVault audit events, a structured logging system designed for compliance requirements like SOC 2 and GDPR. The schema validates audit event files that track actions performed by actors (users, services, or systems) on targets within an application.
Key changes:
- New JSON Schema using draft-07 for LogVault audit event validation
- Test file demonstrating a basic login audit event
- Catalog entry for automatic schema application (not shown in diff but mentioned in PR description)
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| src/schemas/json/logvault-audit-event.json | Defines the schema structure with required fields (action, actorId) and optional fields (actorType, targetId, targetType, metadata, timestamp) |
| src/test/logvault-audit-event/logvault-audit-event.json | Provides a positive test case showing a user.login event with metadata |
| "properties": { | ||
| "action": { | ||
| "type": "string", | ||
| "pattern": "^[a-z][a-z0-9]*([._][a-z][a-z0-9]*)+$", |
There was a problem hiding this comment.
The regex pattern ^[a-z][a-z0-9]*([._][a-z][a-z0-9]*)+$ is overly restrictive and complex. Per SchemaStore guidelines, avoid complex regex patterns that could break with new versions or usage patterns. Consider simplifying this pattern or removing it entirely to allow for future flexibility. A basic pattern like ^[a-z][a-z0-9._]*$ would be more maintainable, or you could rely on the minLength and maxLength constraints alone.
| }, | ||
| "actorType": { | ||
| "type": "string", | ||
| "enum": ["user", "service", "system", "api_key"], |
There was a problem hiding this comment.
The exhaustive enum for actorType combined with additionalProperties: false at line 57 could break when new actor types are introduced in future versions of LogVault. Per SchemaStore guidelines, avoid overly restrictive constraints. Consider either removing the enum to allow any string value, or adding a pattern to allow other values (e.g., by not making this an enum but a suggested list in examples).
| "description": "ISO 8601 timestamp of the event" | ||
| } | ||
| }, | ||
| "additionalProperties": false |
There was a problem hiding this comment.
Setting additionalProperties: false prevents forward compatibility if LogVault adds new fields in the future. Per SchemaStore guidelines, be cautious with this constraint as it can break with new versions. Consider removing this constraint or carefully documenting the versioning strategy if this schema is meant to be version-specific.
| { | ||
| "action": "user.login", | ||
| "actorId": "user_abc123", | ||
| "actorType": "user", | ||
| "metadata": { | ||
| "ip": "192.168.1.100", | ||
| "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" | ||
| } | ||
| } |
There was a problem hiding this comment.
The test file should include examples of optional fields to ensure comprehensive test coverage. Consider adding test cases that include targetId, targetType, and timestamp fields to validate the full schema. Per SchemaStore guidelines, always add adequate test coverage for new schemas.
| "$schema": "http://json-schema.org/draft-07/schema#", | ||
| "$id": "https://json.schemastore.org/logvault-audit-event.json", | ||
| "title": "LogVault Audit Event", | ||
| "description": "Schema for audit trail events. LogVault provides compliance-ready audit logging for SaaS applications.", |
There was a problem hiding this comment.
The description should include a URL reference to the LogVault documentation. Per SchemaStore conventions, descriptions should follow the format <description>\n<url> with the URL on a new line. For example: "description": "Schema for audit trail events. LogVault provides compliance-ready audit logging for SaaS applications.\nhttps://logvault.eu/docs"
| "description": "Schema for audit trail events. LogVault provides compliance-ready audit logging for SaaS applications.", | |
| "description": "Schema for audit trail events. LogVault provides compliance-ready audit logging for SaaS applications.\nhttps://logvault.eu/docs", |
src/api/json/catalog.json
Outdated
| { | ||
| "name": "nest-cli", | ||
| "description": "A progressive Node.js framework for building efficient and scalable server-side applications 🚀", | ||
| "description": "A progressive Node.js framework for building efficient and scalable server-side applications \ud83d\ude80", |
There was a problem hiding this comment.
What's with all the control characters throughout this file?
There was a problem hiding this comment.
Thanks for the review. Rebased and addressed all feedback:
Changes:
- Rebased on latest master (diff now shows only LogVault changes)
- Added docs URL to description
- Removed
additionalProperties: falsefor forward compatibility - Converted
actorTypeenum to examples array - Relaxed regex to
^[a-z][a-z0-9_]*\.[a-z][a-z0-9_.]*$ - Expanded test file with all optional fields
Re: control characters — My editor converted Unicode to escape sequences (e.g., 🚀 → \ud83d\ude80). Fixed by rebasing cleanly on master.
Ready for re-review.
- Schema for audit trail events (user.login, api_key.created, etc.) - Flexible pattern: resource.action format with underscores and nesting - Forward-compatible: no additionalProperties restriction - Docs: https://logvault.eu/docs
Rul1an
force-pushed
the
add-logvault-audit-event
branch
from
0a02528 to
1a91f0c
Compare
for more information, see https://pre-commit.ci
2 participants
Hey there 👋
Adding a schema for LogVault audit events.
What's LogVault?
We're building audit logging infrastructure for SaaS companies. Think "structured logging but for compliance" - SOC 2, GDPR, that kind of thing. Events are immutable and searchable.
The schema
Pretty straightforward structure:
{ "action": "user.login", "actorId": "user_abc123", "actorType": "user", "metadata": { "ip": "192.168.1.1" } }resource.verbpattern)Use cases
Files
src/schemas/json/logvault-audit-event.json- The schemasrc/test/logvault-audit-event/logvault-audit-event.json- Test filesrc/api/json/catalog.json- Catalog entry addedLinks
Happy to make changes. Thanks for maintaining this! 🍻