glx validate

Validate GLX files and cross-references

Synopsis

Validate GENEALOGIX (.glx) files for correctness and integrity.

Performs comprehensive validation including:

• YAML syntax correctness
• Required fields presence
• Entity ID format validation
• Cross-reference integrity (directories and single-file archives)
• Duplicate ID detection (directories only)
• Vocabulary validation (if vocabularies/ exists)

Validation behavior:

• Single file holding a whole archive: full validation, cross-references included. A file counts as a whole archive when it carries its own vocabularies alongside its entities (what glx join writes) or declares every entity collection (what glx init --single-file scaffolds)
• Single file holding a fragment of a multi-file archive: structure and the semantic checks that stand on their own; cross-reference and place-hierarchy checks are skipped, because the entities those references name live in the fragment's siblings, which are not being validated
• Directory: Validates all .glx files with full cross-reference validation
• No arguments: Validates current directory with full cross-reference validation
• Several paths (directories, .glx files, or a mix): Loaded together as one archive rooted at the enclosing archive directory — their deepest common directory, or its parent when that is itself an entity directory such as events/ — so cross-references between them resolve and duplicate IDs across them are caught. The archive's vocabularies/ under that root is included automatically; files that are not .glx are ignored. References to entities outside the named paths are errors: the selection is validated as the archive it would be on its own.

Dot-prefixed directories and files (.git, .glx, .worktrees, ._name.glx) are not archive content and are skipped when a directory is walked, including symlinks that point into them. A dot-prefixed .glx file named explicitly on the command line is validated. An archive whose own root directory is dot-named is still validated normally.

Use --show-first-errors N to limit each error list in any validation mode, including --stdin (default 10, 0 for all). Warnings are always listed in full.

Use --report to generate a confidence summary showing assertion coverage and highlighting unsupported claims. The archive is validated first, so --report fails on an archive that plain validate rejects.

glx validate [paths...] [flags]

Examples

  # Validate current directory (with cross-reference checks)
  glx validate

  # Validate specific directory (with cross-reference checks)
  glx validate persons/

  # Validate multiple paths (with cross-reference checks)
  glx validate persons/ events/ places/

  # Validate a single-file archive (with cross-reference checks)
  glx validate archive.glx

  # Validate one file of a multi-file archive (structure only)
  glx validate events/event-births.glx

  # Generate confidence summary report
  glx validate --report
  glx validate path/to/archive --report

Options

      --entity-type string      Entity or vocabulary type for --stdin — an entity singular (person, event, place, source, citation, repository, media, relationship, assertion, research-log, study) or a vocabulary collection key (e.g. event_types, place_types, confidence_levels, participant_roles)
  -h, --help                    help for validate
      --report                  Generate confidence summary report
      --show-first-errors int   Number of validation errors to show (0 for all) (default 10)
      --stdin                   Read one entity as YAML on stdin and validate it against its entity-type schema (no path args)

Options inherited from parent commands

  -q, --quiet   Suppress non-error output (where supported)

SEE ALSO

• glx - GENEALOGIX CLI - Manage and validate genealogy archives