Add ffigen schema and refer them in example config yaml using modeline

[mannprerak2]

Closes dart-lang/native#468

• Added a schema file
• Refer to schema locally using yaml modeline in example configs.

[mannprerak2]

I've put the schema at the root level in ffigen.schema.json. I am not sure how we proceed though, I just now learned about json schema 🙈 .

[mannprerak2]

Some concerns-

1. We could add additionalProperties: false but I feel it may be misleading since I'm not sure about the delay in publishing new schema and when the user updates their package.
2. Different ffigen versions could have different schema's, is there any way we can handle this?
3. How do we test this?

[dcharkes]

Sweet!

Thanks @mannprerak2 !

[dcharkes]

Some concerns-

1. We could add additionalProperties: false but I feel it may be misleading since I'm not sure about the delay in publishing new schema and when the user updates their package.

That's a good question. I don't really know. What's the behavior? Showing an error or a warning? If it's just a warning, maybe it's fine. Because if you mistype a property you would want to see a warning/error.

2. Different ffigen versions could have different schema's, is there any way we can handle this?

They don't change that quickly right?

I have no idea if the the pub people cc @jonasfj @sigurdm and dartcode @DanTup can tell us something about versioning JSON schemas in vscode via pub packages.

3. How do we test this?

See comment above about generating the schema.

@DanTup might know how to test VSCode things on the GitHub CI.

[DanTup]

Does VS Code support schemas for YAML? There is a RedHat extension (https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) that says it supports them, but I don't think it's built-in.

In which case users would need to install that extension (and configure it, unless the schema is on schemastore.org). I'm not sure we can reasonably make any of that automatic though.

It might be possible to write some tests that set up VS Code, install the RedHat YAML extension and configure it to check that diagnostics/completion work, although I think if the scheme is valid then the rest of that is already tested by the RedHat extension.

[HosseinYousefi]

Installing RedHat YAML extension is required. The schemas are downloaded from https://www.schemastore.org/json/ by default. So we need to upload them there eventually.

---

As @dcharkes mentioned, I'd suggest having this generated automatically.

[dcharkes]

Following the discussions in dart-lang/native#468, I'm happy to land a schema, manually publish it to the schema store, have a stable url of the schema on this repo, and have all the examples point to the one on this repo or the schemastore (maybe pointing to a stable URL on this repo would be best because we can guarantee it to stay up to date).

We should probably version the schema file with the semantic version of the package. https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md

[mannprerak2]

Following the discussions in dart-lang/native#468, I'm happy to land a schema, manually publish it to the schema store, have a stable url of the schema on this repo, and have all the examples point to the one on this repo or the schemastore (maybe pointing to a stable URL on this repo would be best because we can guarantee it to stay up to date).

Cool

For the auto-generation, I'll try to come up with a good abstraction which can handle validation and json schema generation. Will probably need to rewrite Map<List<String>, Specification> _getSpecs

[dcharkes]

For the auto-generation, I'll try to come up with a good abstraction which can handle validation and json schema generation. Will probably need to rewrite Map<List<String>, Specification> _getSpecs

👍

This is probably a general pattern we want, I've filed dart-lang/tools#112 to make a general solution. Feel free to either come up with a general solution, and try it both in package:ffigen and package:native_assets_cli, or to make something package:ffigen specific, and report your experiences on that bug.

[mannprerak2]

Regarding the new schema abstraction. How does it relate to for example https://pub.dev/packages/json_schema or https://pub.dev/packages/json_schema2 ?

They are more focused on having a JsonSchema input than generating a JsonSchema, The classes probably can't be reused (and might change since they aren't part of the public API). Validations are possible if we write the Schema by hand and use that as an initial step.

The custom validation, extraction and default spec part would still remain, so I feel the current approach might be better.

[mannprerak2]

I think this is ready for review now @dcharkes

[dcharkes]

So happy to see red squigglies in my editor! 🎉

[dcharkes]

Do we have any if key a is in this map, then b is required?
Or if a is in this map, then b must not be supplied?

That's probably not expressible in JSON schemas.

But I have some of that kind of logic in package:native_assets_cli. https://github.com/dart-lang/native/blob/main/pkgs/native_assets_cli/lib/src/model/build_config.dart

We would probably model that by referring from one schema to the other. I believe the setup in this PR would work fine with trying to add that.

[mannprerak2]

We can use OneOfSchema for these situations. It might be too complicated though for a lot of if-else, Since we'd need one Schema for each permutation.

[mannprerak2]

Another option supported by JsonSchema as well would be https://json-schema.org/understanding-json-schema/reference/conditionals.html#id6

[dcharkes]

Ah nice! If I find some time, I can give your abstraction a spin and add these, and use it in package:native_assets_cli. If the abstraction works well standalone, we could move it to package:config_cli. 👌

[dcharkes]

Sorry for the 1 million iterations here! 🙈 I think we're ready to land after the renames. 🚀

[mannprerak2]

Sorry for the 1 million iterations here! 🙈 I think we're ready to land after the renames. 🚀

Ah, no problem. It's finally ready now I suppose 🙈

[dcharkes]

Thanks @mannprerak2 !