media-types: show relations between media types

Signed-off-by: Sergiusz Urbaniak <[email protected]>

Makefile

@@ -9,6 +9,9 @@ DOC_FILES := \
 	manifest.md \
 	serialization.md
 
+FIGURE_FILES := \
+	media-types.png
+
 default: help
 
 help:
@@ -23,8 +26,9 @@ fmt:
 docs: output/docs.pdf output/docs.html
 .PHONY: docs
 
-output/docs.pdf: $(DOC_FILES)
+output/docs.pdf: $(DOC_FILES) $(FIGURE_FILES)
 	@mkdir -p output/ && \
+	cp *.png $(shell pwd)/output && \
 	$(DOCKER) run \
 	-it \
 	--rm \
@@ -34,8 +38,9 @@ output/docs.pdf: $(DOC_FILES)
 	vbatts/pandoc -f markdown_github -t latex -o /output/docs.pdf $(patsubst %,/input/%,$(DOC_FILES)) && \
 	ls -sh $(shell readlink -f $@)
 
-output/docs.html: $(DOC_FILES)
+output/docs.html: $(DOC_FILES) $(FIGURE_FILES)
 	@mkdir -p output/ && \
+	cp *.png $(shell pwd)/output && \
 	$(DOCKER) run \
 	-it \
 	--rm \
@@ -48,7 +53,6 @@ output/docs.html: $(DOC_FILES)
 code-of-conduct.md:
 	curl -o $@ https://raw.githubusercontent.com/opencontainers/tob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md
 
-.PHONY: validate-examples
 validate-examples: oci-validate-examples
 	./oci-validate-examples < manifest.md
 
@@ -58,3 +62,9 @@ oci-validate-json: validate.go
 oci-validate-examples: cmd/oci-validate-examples/main.go
 	go build ./cmd/oci-validate-examples
 
+media-types.png: media-types.dot
+
+%.png: %.dot
+	dot -Tpng $^ > $@
+
+.PHONY: validate-examples

media-types.dot

@@ -0,0 +1,14 @@
+digraph G {
+  {
+    manifestList [shape=note, label="Manifest list\n<<optional>>\napplication/vnd.oci.image.manifest.list.v1+json"]
+    manifest [shape=note, label="Image manifest\napplication/vnd.oci.image.manifest.v1+json"]
+    config [shape=note, label="Image JSON\napplication/vnd.oci.image.serialization.config.v1+json"]
+    layer [shape=note, label="Layer tar+gzip\napplication/vnd.oci.image.serialization.rootfs.tar.gzip"]
+    combined [shape=note, label="Combined image JSON and filesystem changesets\n<<optional>>\napplication/vnd.oci.image.serialization.combined.v1+json"]
+  }
+
+  manifestList -> manifest [label="1..*"]
+  manifest -> config [label="1..1"]
+  manifest -> layer [label="1..*"]
+  combined
+}

media-types.md

@@ -41,3 +41,11 @@ This section shows where the OCI Image Specification is compatible with formats
 ### application/vnd.oci.image.serialization.combined.v1+json
 
 - [layout compatible with docker save/load format](https://github.com/opencontainers/image-spec/blob/master/serialization.md#combined-image-json--filesystem-changeset-format)
+
+## Relations
+
+The following figure shows how the above media types reference each other:
+
+![Media Types](media-types.png)
+
+A reference is defined as the target content digest, as defined by the [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter). The manifest list being a "fat manifest" references one or more image manifests per target platform. An image manifest references exactly one target configuration and possibly many layers.