dvc.yaml: very hard to edit, can we detect and do human readable/helpful schema errors?

[shcheklein]

As we are migrating from using dvc run, dvc import-url, and other helpers when we create stages, it makes creating a proper dvc.yaml very painful. Trying to add a stage, I'm getting errors like this:

ERROR: unable to read: 'dvc.yaml', YAML file structure is corrupted: mapping values are not allowed in this context
  in "<unicode string>", line 7, column 14

or this:

ERROR: unable to read: 'dvc.yaml', YAML file structure is corrupted: while parsing a block collection
  in "<unicode string>", line 6, column 7
did not find expected '-' indicator
  in "<unicode string>", line 7, column 9

or this:

'dvc.yaml' format error: expected str @ data['stages']['prepare_genome']['deps'][0]

(from #5370)

or infamous one with size.

From my personal experience you basically have to go to docs and manually compare and experiment until it's fixed.

I wonder if we can produce some meaningful error messages, include examples if needed of the affected section?

[skshetry]

We might be able to add a linter to provide better error message during syntax errors (see: https://github.com/adrienverge/yamllint).

EDIT: Looks like yamllint is GPL 😕

[dberenbaum]

More generically, how can stage creation in dvc.yaml be easier? If dvc run is deprecated, users may find it harder to create stages. Does this need to be prioritized before the 2.0 release?

[dberenbaum]

I forgot about dvc stage add, which should help users create stages without manually editing dvc.yaml and make this less high priority. Regardless, it would be a useful feature for users who do manually edit dvc.yaml.

[dberenbaum]

voluptuous is already being used to perform validation and provide error messages like the last one, right? I wonder if custom exceptions would be more helpful, or if another data validation library provides more useful messages.

[skshetry]

One good workaround around this would be to try to reparse the yaml using YAML(type="rt") on error which provides better error messages and contexts around it (compared to the C-parser).

>>> YAML(typ="rt").load("""
    x:
        y:3
        transitions:
    """)

ScannerError: mapping values are not allowed here
  in "<unicode string>", line 4, column 14:
      transitions:
                 ^ (line: 4)

Also, the provided exception has more details in it this way, which we can use to wrap it and provide better (colorful and structured) error messages.

[skshetry]

And, with Pydantic, the above schema error changes to the following, which is a bit easier to read:

ERROR: 'dvc.yaml' format error: 1 validation error
  stages -> prepare_genome -> deps -> 0
    str type expected (type=type_error.str)

See #5531

[kenahoo]

I suspect that the two <unicode string>s in the error message are supposed to actually be the strings it's looking at, right? Is this just a simple interpolation error?