Takoform

配色

Host API v1 ​

forms.takoform.com/v1 is the literal, provider-neutral Takoform Host API contract. Its normative prose and machine closure are immutable at the bytes named by v1.freeze.json. Errata are non-normative notes and do not reinterpret this lane. Any change to accepted, sent, stored, or observed behavior requires a future Host API v2 proposal. There is no Host API minor lane such as /v1.1, and no separately numbered Specification 1.x lane. The contract installs immutable Form Definitions, accepts desired resources under exact FormRefs, and reports lifecycle state. A passing conformance report is evidence about this contract only; it grants no publication, support, or production-readiness status.

The frozen machine roots and semantic schema roots incorporated by this lane and its common model are:

v1.freeze.json names their complete recursive schema closure. A schema reached through $ref is frozen even when it is not a semantic root in the list above.

Discovery and routing ​

GET /.well-known/takoform/v1 returns exactly one advertised API lane, forms.takoform.com/v1, with API root /apis/forms.takoform.com/v1. service_forms, exact_form_ref, optimistic_concurrency, idempotent_lifecycle, operations, artifact_upload, and support_profiles are required and true.

An advertised endpoint is same-origin with the discovery document. Its escaped path contains no percent-encoding, userinfo, query, or fragment. Plain HTTP is valid only for a loopback development origin.

A current Form Family group is a versionless reverse-DNS name and travels as one ordinary path segment. A group containing / is invalid. The current routes therefore use {formGroup}/{kind}, never a separate family-version segment.

The lifecycle root is:

text
{api}/resources/{formGroup}/{kind}/{name}

The forms, form-definitions, resource, and Form support routes accept or return the complete exact FormRef. No route accepts latest, an omitted definition version, a group-and-kind alias, or a best available definition. Failure to resolve all four FormRef members is form_unknown before mutation.

Exact FormRef ​

A FormRef is exactly:

json
{
  "apiVersion": "forms.example.com",
  "kind": "ExampleResource",
  "definitionVersion": "0.3.0",
  "schemaDigest": "sha256:<64 lowercase hexadecimal characters>"
}

apiVersion is the versionless family group. definitionVersion versions the one Form independently. schemaDigest is the RFC 8785 digest of the immutable Definition. All four members participate in equality, catalog lookup, stored identity, relation pins, idempotency fingerprints, and support answers. packageDigest may accompany a FormRef as audit evidence and never participates in any of those decisions.

Wire and identity rules ​

Every request and response is UTF-8 I-JSON. A Host validates the raw document before typed decoding. Invalid UTF-8, duplicate members, a non-I-JSON number, trailing data, excessive nesting, or an unknown closed-envelope field is invalid_argument before mutation.

metadata.name is a lowercase DNS-like resource name. metadata.space is an opaque, case-sensitive SpaceID. A SpaceID is 1 through 255 Unicode code points, has no leading or trailing Unicode whitespace, and contains no slash or control character. Hosts preserve it without trimming, normalization, or case folding.

Resource identity has three independent Host-issued counters:

  • uid is immutable for one incarnation. Delete and recreate changes it.
  • generation starts at 1 and advances only when portable desired state changes.
  • revision starts at 1 and advances on every representation change, including Host-observed status or output changes.

Generation and revision are canonical positive decimal strings in the signed 64-bit range. A response ETag is exactly one strong quoted revision.

Every response echoes the exact FormRef recorded at creation or import. A request under another definition never reinterprets stored state and never causes a catalog fallback.

Lifecycle ​

The current lifecycle capabilities are create, read, update, delete, import, and observe. A Definition declares the subset it supports. A Host may narrow its own support profile and must never widen the Definition.

validate checks the submitted document and may resolve tenant-scoped UID relations only when the exact Definition declares a resolved-UID constraint; it never decides tenant-specific standard-service satisfiability. prepare materializes portable defaults, validates the exact installed Definition, resolves relations and Host capabilities for the authenticated tenant, and returns a review binding. apply consumes that binding and repeats every mutable-state decision atomically with its write. import performs the same semantic validation before adopting a native identity. observe refreshes Host-observed state without changing desired state. delete removes only the addressed incarnation.

Create requires If-None-Match: *. Update, observe, prepare of an existing resource, and delete require Takoform-Expected-Generation or the equivalent body field where the operation table permits it. If both transports are sent they are equal. If-Match, when sent, carries the exact strong revision ETag. An absent required fence is invalid_argument; a stale generation is generation_conflict; a stale revision is revision_conflict; and an expected UID naming another incarnation is uid_mismatch.

Every mutation requires an idempotency key scoped by authenticated tenant, principal, operation, resource address, and exact request fingerprint. Reusing the key with another fingerprint is invalid_argument. A recorded answer does not outlive the incarnation or operation it reports.

Prepare binds the canonical materialized spec digest, exact FormRef, resource address, current UID and generation (or the create markers), and Host plan. Substitution is invalid_argument before mutation. An accepted asynchronous mutation repeats relation, constraint, claim, capability, artifact, and standard-service checks at commit.

Relations and bindings ​

References are closed {apiVersion, kind, name} objects derived from the installed Definition's desired schema. The source resource's authenticated tenant and metadata.space supply scope; cross-space and cross-tenant lookup is unrepresentable. A missing target is resource_not_found before mutation.

Resolution records the relation pointer, target address, target UID, and target exact FormRef. A target replacement does not retarget the source: it renders the source not Ready until the source is reapplied and deliberately repinned. Deleting a live target with dependents is dependency_in_use.

A typed binding additionally resolves its exact Binding Definition, source role, allowed target FormRefs, and required Interface. A missing contract is unsupported_capability; a contract mismatch is invalid_argument. No Host may infer a binding from names or from a target that merely looks compatible.

Declared constraints ​

A current Form Definition carries a closed top-level constraints array. A Host that does not implement a declared kind refuses installation with unsupported_capability. Constraints are checked at validate or prepare as applicable, on synchronous apply and import, and again inside an asynchronous commit. No declared constraint may be parsed and ignored.

The current constraint kinds are:

  • exclusive: at most one live resource of the exact source Form may hold the referenced target UID, optionally keyed by another desired value.
  • sum: integer members of the declared list total exactly the declared value.
  • claim: one canonical desired value has at most one live claimant per tenant, across spaces.
  • hostAssigned: the Host mints the declared output, keeps it stable for the UID, and accepts no desired-state substitute.
  • orderedPair: the concrete numeric value at the first pointer is less than or equal to the value at the second pointer.
  • uniqueBy: every object in the declared list has a distinct canonical scalar value for the declared member. Equivalent JSON number spellings compare equal; strings and numbers remain different domains.
  • acyclic: following the declared relation through live UID-pinned resources never reaches the source UID and never forms a cycle. Traversal is bounded; an unreadable or replaced edge fails closed.
  • distinctPair: when both optional relations are present, they resolve to two different immutable UIDs.
  • uniquePair: the ordered pair of resolved UIDs is held by at most one live resource per tenant and exact FormRef. Reverse order is a different pair.
  • sameResolvedTarget: the anchor relation and every relation reached through the declared member list and member pointer resolve to the same immutable UID.

Checks and writes for exclusive, claim, and uniquePair are serializable or use an equivalent atomic reservation. A prepare-only implementation is not conforming because two prepared requests could otherwise both commit.

Standard services ​

A desired-schema property annotated x-takoform-standard-services: standards.takoform.com/v1 contains sealed {name, service, required?} slots. required defaults to true. service is an exact current StandardServiceRef:

json
{
  "apiVersion": "standards.takoform.com/v1",
  "protocol": "com.amazonaws.s3"
}

protocol is an opaque normalized reverse-DNS identifier with at least three labels and at most 253 characters. Takoform defines no central protocol enum. Syntax validity does not claim protocol conformance and does not imply Host support.

Support is Host- and tenant-specific:

text
GET {api}/support/standard-services/{protocol}

The response is support.takoform.com/v1, kind StandardServiceSupport, echoes the exact current StandardServiceRef, and carries a boolean satisfiable. A grammar-valid unknown identifier receives a 200 profile with satisfiable: false; it is not a missing Takoform registry entry.

A Host may support a structured object-storage protocol such as com.amazonaws.s3. A required unsupported slot is unsupported_capability at prepare and again before any direct or asynchronous mutation. An optional unsupported slot blocks nothing and projects nothing. Resolved endpoints, credentials, secrets, passwords, and vendor configuration never appear in desired state, observed state, outputs, diagnostics, client state, or support profiles.

Artifacts and operations ​

Artifact manifests and blobs are content addressed. A digest identifies bytes, not authority. The authenticated tenant must already hold every referenced manifest and blob. A foreign or unknown digest is indistinguishable and fails as artifact_missing. Commit revalidates the manifest kind, declared size, entry count, content digests, and every Form-specific artifact rule.

A mutation returning HTTP 202 returns an Operation handle bound to the creating tenant and principal. A foreign caller receives operation_not_found, not a confirmation that the handle exists. Pending Operations carry neither result nor error. A terminal Operation carries exactly one. Terminal errors require a request ID and retryable: false; starting a new operation is a caller choice, not a continuation of a completed record.

Conditions, outputs, and errors ​

The portable condition types are Ready, Reconciling, Degraded, Drifted, Blocked, and Deleting. Portable reasons are Available, Provisioning, ExternalChange, DependencyMissing, and UnsupportedCapability, only in the type/reason combinations defined by the wire schema. Host-specific detail is optional and never required for portable interpretation.

Outputs are present exactly when the installed Definition declares an outputSchema, validate against that exact schema, and contain no undeclared member. Host-observed details not declared as portable outputs remain outside the resource representation.

The closed error codes are invalid_argument, unauthenticated, permission_denied, form_unknown, form_not_installed, form_unavailable, resource_not_found, resource_busy, import_conflict, policy_denied, backend_unavailable, internal_error, rate_limited, deadline_exceeded, operation_cancelled, operation_not_found, dependency_in_use, artifact_missing, artifact_invalid, unsupported_capability, migration_required, uid_mismatch, revision_conflict, and generation_conflict. HTTP status and automatic retryability are fixed by operations-v1.json. An implementation never adds a new portable code or reason under this lane.

Conformance ​

The current generic artifact corpus is ../../conformance/takoform-v1/generic.json. It verifies package bytes, exact Interface and Binding contract bytes, and the compiled immutable Snapshot. It is deliberately not a Host lifecycle runner: it does not execute create/read/update/delete, optimistic-concurrency fencing, relation mutation, runtime code, activation, Host Support, or every publisher's family semantics. Hosts and publishers provide those independent evidence sets through their own boundaries. Retained predecessor corpora remain historical artifacts and are not rewritten by the generic corpus.

normative source は tako0614/takoform。realized DNS と配信 account は公開 operator の authority です。

MIT © 2026 Takoform contributors