Compose: 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 https://github.com/docker/libcompose/issues/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 :boat:

[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

[dnephin]

We should do #2704 before we go to formalize the schemas

[abitrolly]

Links to specification proposals became broken. They are here https://github.com/docker/compose/tree/master/compose/config

[thaJeztah]

The specs for the 3.x compose format now live in https://github.com/docker/cli/tree/master/cli/compose/schema/data (which is leading), and a copy of those in this repository.

I'd personally still be "+1" to have those specs in a separate repository thought, to make it more explicit where the official specs live.

[anodynos]

If you can publish the specs in http://schemastore.org/json/ it would be great. IDE's like IntelliJ Idea & I assume others use schemastore.org's schemas for dev support. Thanks

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[thaJeztah]

.

[stale[bot]]

This issue has been automatically marked as not stale anymore due to the recent activity.

[ZiQiLN]

I've done everything that I could, I've pushed PR to SchemaStore going through all issues related to the specification of Compose files.

https://github.com/SchemaStore/schemastore/pull/1153

[bfirsh]

In case anyone stumbles across this issue, this exists now: https://github.com/compose-spec/compose-spec

Guess we can close the issue?

[ZiQiLN]

Sure we can close this issue I think, compose-spec has also issue related to schema SchemaStore, and I've resolved it.

https://github.com/compose-spec/compose-spec/issues/50#issuecomment-662704750

[ZiQiLN]

Reference to resolved PR: https://github.com/SchemaStore/schemastore/pull/1153

The issue can be closed for sure :)