Score Specification: A Workload Spec That Generates Docker Compose and Kubernetes Output

What Score solves, and who ends up writing score.yaml

The README frames the problem in terms of duplicated configuration. A developer who runs Docker Compose locally but deploys to a Kubernetes-based environment has to learn both formats and keep them in sync. Score's answer is a single file per workload, saved next to the source code in version control, that describes runtime requirements in a vendor-neutral way. The README's example describes a web server that queries a Postgres database, and it names three resources: a postgres database, a dns entry and a route. None of those carry platform syntax. The audience is the application developer, not the platform engineer. The README says Score is "tightly scoped" and does not intend to be a full YAML replacement for Kubernetes, which is a deliberate boundary: the file stays short because it stops at workload-level properties. That boundary also means Score is the wrong tool for anyone who needs to express cluster-level concerns such as node affinity, admission policy or cluster-scoped operators. Those belong to the platform, and the spec does not model them.

How a score.yaml becomes docker-compose.yaml or manifests.yaml

The mechanism is a translation step performed by a separate program called a Score implementation. The README describes the flow directly: once the workload's runtime requirements are defined with the specification, a Score implementation translates it into the desired target output format. Two reference implementations are named. score-compose converts a Score specification into a docker-compose.yaml file. score-k8s generates manifests.yaml files for a Kubernetes cluster. The schema lives in this repository as score-v1b1.json, and the apiVersion field in a Score file, score.dev/v1b1, is what ties a given file to that schema version. Inside the file, resources are declared by name and type, and their outputs are referenced with placeholder syntax such as ${resources.db.host}. The README notes that the implementation takes care of securing secret access when those placeholders are passed into container environment variables. This is the contract the README describes between dev and ops: the developer lists requirements, the platform resolves them. The spec repository itself contains no translator, which is the single most important structural fact about it.

Installing Score and validating your first spec file

There is no Score binary to install from this repository. What you clone here is the schema, the samples and the Makefile that checks them, so the practical first step is cloning the repo and running its own validation targets. The Makefile installs a JSON Schema validator into your GOPATH on demand, so GOPATH must be set or the build fails with an explicit error. The help target lists the documented targets.

git clone https://github.com/score-spec/spec.git
cd spec
make help

After make help you should see the documented targets test-schema, test-examples and test, each with its comment line.

To confirm the schema itself is a valid JSON Schema document, run the schema target. It invokes jv against score-v1b1.json using the 2020-12 dialect.

make test-schema

A passing run prints "Schema is a valid jsonschema". Then validate the bundled examples, which is the closest thing to a first real use of the spec. The examples directory defaults to ./samples and can be overridden with SCORE_EXAMPLES_DIR.

make test-examples
SCORE_EXAMPLES_DIR=./samples make test-examples

A passing run prints "Schema matches all samples". To write your own, copy the shape of the README example: set apiVersion to score.dev/v1b1, give the workload a metadata.name, declare at least one container with an image, and add a resources block. Save it as score.yaml and point the validator at it with jv, then hand the file to score-compose or score-k8s for the actual translation.

Where the specification stops and the implementations begin

The most common misreading of this project is expecting it to deploy something. It does not. The README is explicit that implementations translate the spec, and that the two reference implementations live in separate repositories. The consequence is that resource types are not defined by the specification alone: the README says each resource dependency has a name and definition that helps the Score implementation link or provision the required resource. If your implementation does not know the type postgres, the spec still validates but the translation fails. That is a real failure mode and it sits outside this repository's test coverage. The Makefile checks that the schema is valid and that the bundled samples conform to it. It cannot check whether a given implementation supports a given resource type. So a green make test run tells you your YAML is well-formed against score-v1b1.json and nothing more. The README also notes that community-built implementations are typically hosted and maintained by their creators, which means support expectations vary by implementation rather than by the spec.

Score against Helm for the same workload

Helm is the obvious comparison point because both produce Kubernetes manifests from a versioned file. The difference is the starting point. A Helm chart describes how to render Kubernetes objects: you write templates, values files and helper functions, and the output is whatever the templates say. Score starts from the workload and stops before the platform. The README states that Score describes workload-level properties and does not intend to be a fully featured YAML replacement for any platform, and that it shields developers from the complexity of container orchestration tools like Kubernetes. In practice that means a Helm chart author must know Deployment, Service and Ingress shapes; a Score author writes containers, service ports and resources, and lets the implementation decide the rest. The trade-off runs the other way too. Helm gives you direct control over every manifest field, while Score gives you only what the schema models. If your workload needs a field the schema does not carry, Score cannot express it and you are back to platform-specific configuration.

Maintenance, versioning and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-07. Releases are infrequent: 0.4.1 on 2026-05-25, 0.4.0 on 2026-04-17, and 0.3.0 on 2025-04-14. That cadence matters for planning. The schema version is encoded in the file itself through apiVersion: score.dev/v1b1, so a workload written today keeps pointing at v1b1 regardless of what the repository does next, and the schema file score-v1b1.json is versioned in the repository root. Upgrading the schema is therefore a deliberate act rather than a side effect of pulling. The licence is Apache-2.0, which permits commercial use and modification with the usual attribution and notice requirements, and the repository also carries a Contributor Covenant code of conduct and a SECURITY.md. None of this is legal advice; if you plan to redistribute a modified schema or embed it in a product, read the LICENSE file in the repository rather than this summary. The practical upgrade cost is low because the artifact you depend on is a JSON Schema document, not a runtime.

What the samples directory tells you before you write anything

Two files in samples/ are worth reading before drafting your own spec. samples/score-full.yaml exercises the breadth of the schema, and samples/score-deprecated-files-and-volumes.yaml shows fields that have been deprecated, which is useful if you are migrating an existing file or reading older documentation. The Makefile's test-examples target walks that directory with find and validates every file matching score*.yaml, so any file you add there is checked by the same command. That is a cheap way to test a schema change or a new resource shape without setting up an implementation. Note the naming pattern the target expects: files must match score*.yaml to be picked up, so a file named my-app.yaml in samples/ will be silently skipped by make test-examples.

Editorial conclusion

Adopt Score if your team currently maintains parallel Docker Compose and Kubernetes configuration for the same workload and wants one declarative file per service. Do not adopt it if you need a deployment tool today: this repository ships the schema, samples and validation targets, not a deployer, and the README points to score-compose or score-k8s for that. Before committing, clone the repo and run make test-examples against samples/score-full.yaml to confirm the schema accepts the resource types you plan to use, then check whether your target platform has an implementation at all, because the README states community implementations are hosted and maintained by their creators.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. score-spec/spec on GitHub