Bring schema in house

[pd93]

Since the Taskfile schema was added to SchemaStore/schemastore, it has slowly diverged as features have been added and documentation changed. This means that users are often left with an error message in their editor saying that a field is not supported when it is.

This PR brings the Taskfile schema back into the Task repo. This will allow us to ensure that it is updated whenever a new feature is added and that users will not run into errors when they shouldn't.

In order to get this to work properly, we will need to update the schema in SchemaStore/schemastore to look like this:

{
  "$ref": "https://raw.githubusercontent.com/go-task/task/master/schema/taskfile-schema.json",
  "title": "Taskfile YAML Schema"
}

A good example of another project that already does this is MarkdownLint. You can see the schema here and the reference in schemastore here.

Once this change is merged and the schemastore reference is updated, we should also update the contribution guide to ask contributors to keep the schema up-to-date when making changes.

---

In addition to bringing the schema in-house, I've also updated the schema descriptions and the docs so that they match (updating both where appropriate) and I've reordered all the keys in both so that they appear in the same order as the Go structs. This makes it much easier to "spot the difference", so it is less likely that keys are missed in the future.

[pd93]

Quick note. I know that single commits are preferred, but I thought it would be slightly easier to review as separate commits since the first commit is just copying the schema as-is and the other two allow you to see the changes that I've made. I'm happy to squash these once reviewed.

[andreynering]

Hi @pd93,

This makes sense. I didn't know it was possible to reference another file via a URL to make this possible.

Some comments:

1. We need to make sure the schemastore project would allow us to reference our schema via a URL instead of having the definitions there. I found only a few schemas the does this there, but seems that it would be allowed indeed.
2. I think it would be more appropriate to move the file to the docs like /docs/schema.json. This way we could reference it via the website (https://taskfile.dev/schema.json) instead of a GitHub URL. What do you think?

[pd93]

1. We need to make sure the schemastore project would allow us to reference our schema via a URL instead of having the definitions there. I found only a few schemas the does this there, but seems that it would be allowed indeed.

Yeah, agreed. I think the first step would be to get this merged and then I can open a PR on their side. and ask @madskristensen if this is the correct approach. If it's not, we can always revert this change. Nothing will change until a PR is merged in schemastore anyway.

2. I think it would be more appropriate to move the file to the docs like /docs/schema.json. This way we could reference it via the website (https://taskfile.dev/schema.json) instead of a GitHub URL. What do you think?

This is a great idea, I've pushed a change.

[andreynering]

Thanks @pd93!