Table of Contents

Metadata check

Metadata check can be started by using the neos check-metadata command in the cluster folder. The output show errors and warnings that have been detected.

Ignoring errors

Although this is not generally recommended, it is possible to ignore metadata-related errors.
This can be useful when dealing with module dependency issues.

Each persistence error is identified by a letter and a unique number (i.e.: N102).
It is possible to ignore them by adding the YamlIgnoredErrors property and listing the error numbers to ignore (without the letter) in the YAML configuration of your cluster:

YamlIgnoredErrors: [102, 105]
Note

The updated configuration is taken into account immediately, there is no need to restart Neos Studio.

Warning

The errors will also be ignored in Neos Studio.
Ignoring errors must remain a temporary solution. Remember to delete the line in the configuration as soon as you no longer need it.

Warnings

Warnings correspond to YAML files which do not contain exactly the expected content or which should not exist. You can use the --diff option to generate two files check-metadata.actual.txt and check-metadata.expected.txt at the root of your cluster:

neos check-metadata --diff

By comparing these two files with a file comparator, you can analyze the differences between your current metadata and the expected versions.

The command can update all the files and thus remove warnings by using the --fix option:

neos check-metadata --fix

You can ask check-metadata to compute an expected formatted version for specific metadata contents with the --format option:

neos check-metadata --format

If --format is omitted, no metadata formatting is applied.

Using --format without a value is equivalent to --format all.

Without --fix, the command reports a warning when the current content differs from the expected formatted content.

When --fix is also used, the file is rewritten so the content matches the expected formatted content.

This option only applies to auto-formattable contents embedded in metadata:

  • XML UI templates
  • embedded C# code

Supported values are:

  • all: reformat XML templates and embedded C# code
  • template-values: reformat XML templates only
  • csharp-values: reformat embedded C# code only

Neos Studio auto-formatting

You can also enable automatic metadata formatting in Neos Studio when saving changes from the graphical editor by configuring the cluster YAML file:

YamlPersistence:
	TemplateValueAutoFormatting: true
	CSharpValueAutoFormatting: true
  • TemplateValueAutoFormatting: auto-formats XML template values during YAML serialization
  • CSharpValueAutoFormatting: auto-formats embedded C# values during YAML serialization

You can enable only one of these options if you want formatting for a single value category.

Command options

The neos check-metadata command supports these options:

  • --diff, -d: generates check-metadata.actual.txt and check-metadata.expected.txt at the root of the cluster when differences are found.
  • --fix, -f: rewrites modified YAML files and deletes obsolete YAML files.
  • --check-constraints, -cc: runs entity constraint validation. By default, it is enabled when --file is used and disabled otherwise.
  • --check-localizable-strings, -cls: runs partial localizable string validation. By default, it is enabled when --file is used and disabled otherwise.
  • --warnaserror, --warn-as-error, -wae: treats warnings as errors and returns an exit code of 1 even if the command reports only warnings. By default, it is enabled.
  • --file, -fi: checks one metadata file by path or file name.
  • --format, -fo [all|template-values|csharp-values]: computes the expected formatted content for auto-formattable metadata values. Without --fix, a warning is reported when the current content differs. With --fix, rewritten files are updated to match the expected formatted content. Without a value, it defaults to all. When omitted, no metadata formatting is applied.
  • --ignore-module-dependencies, -imd: ignores modules located under modules/dependencies during the metadata check.

Typical usages:

neos check-metadata --file modules\MyModule\metadata\Entities\MyEntity.yml --fix
neos check-metadata --fix -cc -cls
neos check-metadata --fix -cc -cls --format
neos check-metadata --format
neos check-metadata --fix --format template-values

Exit code

By default, the exit code is 1 if the command reports error(s) or warning(s) and 0 otherwise. You can disable this behavior for warnings with the --warnaserror false option.

Element accessibility across modules

Since Neos 3.2, a metadata element can declare Accessibility: Internal to restrict it to its own module plus the modules its module explicitly grants access to (see Module accessibility). check-metadata validates every modeled cross-module reference to such an element, the same way it already validates module dependencies: a reference from a module that hasn't been granted access is reported as error N108, ignorable the same way as any other persistence error:

YamlIgnoredErrors: [108]

This also covers overrides — a module cannot override a value of an Internal element it doesn't have access to — and it revalidates existing overrides when a module's InternalAccessGrantedTo grant shrinks, even if those overrides weren't otherwise touched in the same save.