Templates

Check a template document

Check a template document against the schema and the rules the publish path applies, without publishing anything. Nothing is stored and no ref is claimed, so this is safe to call on a draft and safe to call repeatedly.

The body is the document itself, as JSON or YAML — not a JSON wrapper around it. Send Content-Type: application/yaml or application/json; either is read.

A document that is wrong is reported with every problem one pass can reach rather than the first, so a file with four mistakes takes one call — see problems in the response for the one case where fixing a problem reveals another. On success the two digests come back: doc_digest identifies the document and changes with anything that changes what it MEANS, and build_digest covers only what decides the image — so a new label or a version bump leaves it alone. build_digest is present only for a document with no spec.from, and such a document builds nothing: spec.build and spec.env need a parent. A document that names a parent in spec.from — which is every document that builds — has no build_digest, because that cannot be computed without the parent image’s, so comparing it cannot tell you whether an edit to such a document means a rebuild.

Requires the member role or higher.

post/templates/validate

Request

  • Base URL: https://app.mandala.computer/api/v1
  • URL: https://app.mandala.computer/api/v1/templates/validate
  • Auth: HTTP bearer

Response

valid is what you branch on, and both branches are 200: an invalid document is an answer to the question, not a failed request. false brings problems and nothing else; true brings the ref, the digests, the catalogue row and the canonical bytes.

Three of the fields below — template, canonical and build_digest_needs — were on this wire and in no reader’s copy of it until OPL-4179, which wrote them out here in prose. OPL-4190 gave the response a schema, so the table is now held against the code that produces it rather than kept in step by hand. In the same change template stopped carrying the on-host image family, which is ours rather than yours and was already projected away on every other route that answers a catalogue row.

validboolean required

Whether the DOCUMENT is well formed — the schema and the rules that read the file itself. It is not a publish preflight: a valid document is still refused by POST /templates for things only your account decides, and none of them are visible here — a namespace that is not yours, a plan that does not carry publishing, a ref already taken, the per-account ceiling, an os that contradicts the family the document names, a spec.hardware.disk_gb below the disk floor of the family or of the spec.from parent (400), and a document with spec.build steps or spec.env naming a family that is not yours (403).

problemsstring[]

Present when valid is false. A document that could not be PARSED has exactly one entry, because nothing after the syntax error was read. A document that parsed is reported with every problem one pass can reach rather than the first, so a file with four mistakes in four fields takes one call — with one exception worth knowing: a build step that is structurally wrong (it does nothing, or carries more than one operation) is reported as that, and the problems INSIDE it are not looked at until you have fixed it. Each names what is wrong in the author’s own vocabulary.

refstring

namespace/name@version, as the document’s metadata spells it.

doc_digeststring

Identifies the document, as sha256:…. Taken over canonical below — so it changes with anything that changes what the document MEANS, a label included, and NOT with comments, key order, indentation or YAML-versus-JSON, none of which survive parsing. Being over canonical is also what lets you check it yourself.

canonicalstring

The document as the digests were taken over it, with key order and whitespace normalised. Two files differing only in comments and key order are the same document and hash the same.

build_digeststring

Covers only what decides the image, as sha256:… — so a new label or a version bump leaves it alone. Present only for a document with no spec.from, which builds nothing (spec.build and spec.env need a parent), so it cannot tell you whether an edit to a document that builds means a rebuild. Replaced by build_digest_needs on a document with a parent.

build_digest_needsstring

Replaces build_digest on a document that names a parent in spec.from: a sentence saying what could not be computed. A build digest needs an identity for the CONTENTS of the base image, which is a fact about a host holding it rather than anything in your document.

Changes

No recorded changes to this operation across all 1 revision of this API.