Providing meta information (like schema file)

[timonf]

Hi there!

I just want to drop an idea here (maybe for YAML 1.3?). Actually there are two "directives" available:

• %YAML to identify the version of YAML
• %TAG to use as a shortcut for URI prefixes

It would be handy to have another one to add:

• %META to add any kind of meta information, which will not be parsed
• or more specific: %SCHEMA to specify a schema file.

Example:

%YAML 1.3
%SCHEMA https://getcomposer.org/schema.json,json-schema
---
name: foo/bar-package
type: project
description: Composer example project

Schema directive:

%SCHEMA <schema uri>[,<schema type>[,<schema version>]]

Another examples:

%SCHEMA resource.rx.yaml,rx
%SCHEMA composer_schema.json,json-schema,draft-04
%SCHEMA schema01.yaml,Kwalify

I think it's important to support multiple systems using the second parameter. If you don't like the idea, I hope for something like a meta directive to add information such a schema document.

What do you think about this idea?

[ssbarnea]

This is clearly a must as YAML become a very popular and maintaining mappings between filenames and schemas proved to not scale well at all. It totally makes sense to declare schema within the file itself.

I am sure lots of authors will be happy to follow a guidance made be YAML spec maintainers.

[nervo]

Oh hello @ssbarnea nice to see you here :)

[ssbarnea]

@nervo It seams that I am trying to make friends (or foes) on many open source projects, maybe too many.

What is really sad is that we didn't get any kind of feedback from people that have the power to implement these changes.

I really needed a solution where the YAML file itself would expose who owns it, so editors could use the correct schema. Good example ansible files, which can be of 3-4 types by themselves. Without YAML spec helping us with some guidelines, we are hopeless.

Having some provisional guidelines before it becomes part of the spec it would be useful, as we can start implementing it as experimental (as long it does not break a YAML 1.1/1.2 parser).

[apupier]

so editors could use the correct schema

Depending on the editor that you are using, you can rely on this convention https://github.com/redhat-developer/yaml-language-server#using-inlined-schema

# yaml-language-server: $schema=<urlToTheSchema>

You can also think to provide specific IDE extension in some cases. I published recently https://developers.redhat.com/blog/2020/11/25/how-to-configure-yaml-schema-to-make-editing-files-easier/ which can give you some ideas.

that said, all of that is only to fill a gap in specification. Having it in the specification itself would be really better

[ingydotnet]

There's a lot of information just around the corner on YAML language change proposals. Many of them involve new directives and schema related topics.

Some of the directives ideas are:

%schema ...  # indicating a schema document
%import ... # pull in other files to stream and adding stream level anchors
%feature ... # parser level features required (that may or may not be supported)

There is also the idea of extending the %YAML tag:

%yaml 1.3 schema=... import=... feature=...

I don't want to get into it to much here since proper info is coming soon, but @ssbarnea pinged us to respond here, so there you go.

See: https://github.com/yaml/yaml-spec/tree/master/rfc

[yufeih]

Any chance this gets added to the spec so we have a standard way of representing schema in YAML?

[gjrtimmer]

This would be a very good addition.

Take the following use case: spring boot microservices with yaml configuration. In this use case you can have several features of your microservice defined within the service yaml file. I'm loading my configuration from a spring boot config server. Would be great if I have the ability to define the schema in the file.

When you use a folder for your microservice in spring cloud config the yaml files in that folder are loaded, and with the spring boot convention they can be called application.yml which makes this request very important in cloud architectures.

I hope this will be considered soon.

[mkstephenson]

This would be a great addition which we could really use. We currently use the yaml-language-server syntax (# yaml-language-server: $schema=http://example.com/schema.json) but that only works for those tools that use the yaml-language-server like VS Code.

[homotechsual]

This is so sorely needed - a cross-platform / standard method for specifying the schema to validate against.

[pantoniou]

For what is worth, I'm currently working on that.

It's going to take a while, but right now I have the hooks for C/C++ via libclang (by annotating the type definition of the structures in the header, similar to what golang does). Eventually I will add other language support and generic YAML schema since it's all just a different backend (and C/C++ is actually the hardest ones, since it doesn't have native reflection).

Also, schemas will be (should be anyway) round-trippable, so you should be able to generate schema/type definitions from any source to any other destination schema, so you could write your schema in what your are most comfortable with (typescript models, YAML schema, golang definitions) and then the framework will be able to generate a type definition that will unserialize the document in another language.

[ingydotnet]

There's really no reason you can't do something like this now in YAML 1.2:

%YAML 1.2
--- !<tag:getcomposer.org,2023:schema.json+json-schema>
name: foo/bar-package
type: project
description: Composer example project

tagging the root node with whatever you deem good enough.

Then for any configurable loader like pyyaml, you could register a constructor function to that tag that invoked the validator of your choice.

https://play.yaml.io/main/parser?input=JVlBTUwgMS4yCi0tLSAhPHRhZzpnZXRjb21wb3Nlci5vcmcsMjAyMzpzY2hlbWEuanNvbitqc29uLXNjaGVtYT4KbmFtZTogZm9vL2Jhci1wYWNrYWdlCnR5cGU6IHByb2plY3QKZGVzY3JpcHRpb246IENvbXBvc2VyIGV4YW1wbGUgcHJvamVjdAo=