Formal specification of Compose file

[bfirsh]

We now have a JSON Schema definition of a Compose file:

https://github.com/docker/compose/blob/master/compose/config/service_schema.json https://github.com/docker/compose/blob/master/compose/config/fields_schema.json

We should probably:

• Put this somewhere so it can be shared by libcompose Strict yaml validation? docker-archive-public/docker.libcompose#34 . This could probably just be in same repository (like Docker's image specification in https://github.com/docker/distribution ), but at some point we might want to be adventurous and put it in a separate repository.
• Attach a human readable definition of the specification. This could be just a high-level overview, which points at the JSON schema and docs. Or perhaps adapted from the YML definition in the documentation. Or perhaps auto-generated somehow. Not really sure what's best here.

[dnephin]

As part of this I think we need to add a version and follow semver when we make changes.

I think it might also be a good idea to try and combine the two schemas into a single schema. I think we can still validate against nested schemas, so we should be able to continue to support abstract base services even with a single schema.

[mnowster]

+1 on semver.

It started out as a single schema but was split to cater for the 2 stages of validation and abstract services. Schema has it's limitations and I'm not sure how re-joining it and catering for the abstract base would work. Be interesting to see how that one pans out and if you have plans, do a spike on it to see what's possible, before we release and share with libcompose.

I'm not super convincedif it'd be worth the amount of effort and complexity to re-join. Hmm. Would need more headspace to think about it some more and with access to how other people would intend to use it.

[dnephin]

You can treat every nested schema exactly the same way you treat a top-level schema in a different file. So using a single file schema, we can support the 2 stage validation by passing in the path to the nested schema for the first phase.

[mnowster]

When I tried that previously, I couldn't get it to work, I wonder if that's because I hadn't got the RefResolver working at that point. Hmm. Interesting. Ok cool. I'll be happy for someone else to work on that area of code for a while, I need a break from it ⛵

[dnephin]

Oh ya, I remember that getting the RefResolver to work was really difficult when I did it

[dnephin]

We should address #2299 before we publish a format spec as well

[thaJeztah]

Are we still considering moving the specs to a separate repository? It may make sense, as it would allow tagging a version if the specs are changed. Separating "specs" and "implementation" (compose, libcompose) sounds logical to me. (Also, it would be in line with in the process we're in to split packages in docker/docker to smaller repositories)

[dnephin]

Yes, I think we should do that