Metadata errors are not debuggable

[jayrbolton-karius]

I'm running hasura metadata apply with the following contents in my databases/databases.yaml file, which I'm basing off of the docs found here: https://hasura.io/docs/latest/graphql/core/migrations/reference/metadata-format.html#databases-yaml

- name: mydb
  kind: postgres
  configuration:
    connection_info:
      database_url:
        from_env: HASURA_DB_URL
      pool_settings:
        idle_timeout: 180
        max_connections: 24
        retries: 1
  tables: "!include databases/mydb/public_tables.yaml"
  functions: []

I get this error:

FATA[0002] error applying metadata
{
  "path": "$.args.metadata",
  "error": "key \"sources\" not found",
  "code": "parse-failed"
}

Which doesn't give me useful information. Where should this key go? What file? What data path?

If I wrap my databases array in a sources: key, then I get

FATA[0000] error applying metadata
cannot build sources from project: error parsing metadata
object: sources
file: databases.yaml
error: parsing error: yaml: unmarshal errors:
  line 1: cannot unmarshal !!map into []sources.SourceWithNormalFields

Which is even less useful than the first error. I found this struct in the source:

graphql-engine/cli/internal/metadataobject/sources/sources.go

Line 26 in 33d6025

type SourceWithNormalFields struct {

. But that doesn't give me enough information for solving this. FYI, I encountered these non-debuggable errors during the very first few steps trying to set up a new Hasura project. I eventually got things working by doing all configuration through the UI console, and then running hasura metadata export in my repo root. I guess I'll avoid manually editing any yaml files :/

My feedback on what would be useful improvements:

• Documentation on the actual metadata type schema (eg use json-schema) with descriptions of every field
• Error messages that actually tell me what the issue is (what file, what yaml path, what the correct type schema is supposed to be etc)
• hasura metadata validate command with useful errors
• Example repos of Hasura configurations