{
  "format": "takoform.host-api@v1beta1",
  "apiGroup": "forms.takoform.com/v1beta1",
  "discoveryPath": "/.well-known/takoform/v1beta1",
  "wireSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json",
  "requiredFeatures": [
    "service_forms",
    "exact_form_ref",
    "optimistic_concurrency",
    "idempotent_lifecycle",
    "operations",
    "artifact_upload",
    "support_profiles"
  ],
  "optionalFeatures": [],
  "requiredEndpoints": ["api"],
  "optionalEndpoints": ["artifacts", "operations", "support", "oidc_issuer"],
  "pathShape": {
    "namespacedGroup": "two-ordinary-path-segments-formGroup-then-formVersion",
    "percentEncodedSlash": "never-in-any-path-segment",
    "formRefApiVersionString": "unchanged-in-bodies-responses-and-the-group-query-key",
    "advertisedEndpointPaths": "must-carry-no-percent-encoding"
  },
  "handleOwnership": {
    "operationId": "bound-to-the-creating-tenant-and-principal",
    "uploadId": "bound-to-the-creating-tenant-and-principal",
    "foreignOperation": "operation_not_found/404",
    "foreignUpload": "artifact_missing/404",
    "unknownUpload": "artifact_missing/404-on-continue-commit-and-abandon-alike",
    "rationale": "403-would-confirm-that-the-handle-names-a-real-record"
  },
  "artifactAccess": {
    "manifestRead": "only-for-a-caller-whose-tenant-holds-the-manifest",
    "blobHead": "only-for-a-caller-whose-tenant-holds-the-blob",
    "foreignManifest": "artifact_missing/404",
    "foreignBlob": "404",
    "holding": "acquired-by-uploading-the-bytes-or-committing-a-manifest-that-names-them",
    "missingBlobs": "answered-per-tenant-not-per-byte-store",
    "deduplication": "physical-storage-may-be-shared; authorization-is-not"
  },
  "identity": {
    "uid": "host-issued-immutable; delete-and-recreate-changes-uid",
    "generation": {
      "encoding": "canonical-decimal-string",
      "minimum": "1",
      "maximum": "9223372036854775807",
      "increments": "only-on-portable-desired-spec-change",
      "fence": "expectedGeneration-or-Takoform-Expected-Generation",
      "fenceRequiredOn": ["update", "observe", "prepare-on-existing", "delete"],
      "absentFenceFailure": "invalid_argument",
      "staleFailure": "generation_conflict"
    },
    "revision": {
      "encoding": "canonical-decimal-string",
      "minimum": "1",
      "maximum": "9223372036854775807",
      "increments": "on-any-representation-change",
      "etag": "exactly-one-strong-quoted-revision",
      "fence": "If-Match",
      "fenceOptionalOnDelete": "honored-when-sent; never-required; a-teardown-moves-revisions-it-does-not-own",
      "staleFailure": "revision_conflict"
    },
    "packageDigest": "audit-evidence-only; never-identity-query-or-fence"
  },
  "prepareBinding": {
    "specDigest": "rfc8785-canonical-spec-digest",
    "prepareDigest": "binds-specDigest-identity-uid-generation-and-host-plan",
    "substitution": "invalid_argument-before-mutation"
  },
  "idempotency": {
    "header": "Idempotency-Key",
    "namespace": ["authenticated-tenant", "authenticated-principal", "space", "key"],
    "fingerprint": ["method", "request-target", "preconditions", "body-bytes"],
    "conflict": "invalid_argument",
    "replay": "recorded-status-etag-body"
  },
  "wireJSON": {
    "encoding": "utf-8-i-json",
    "rawDocumentValidation": "before-typed-decoding",
    "duplicateMember": "invalid_argument-before-mutation",
    "unknownEnvelopeField": "invalid_argument-before-mutation"
  },
  "relationResolution": {
    "derivedFrom": "installed-form-definition-desiredSchema",
    "referenceShape": "closed-object-requiring-apiVersion-kind-name-with-const-apiVersion-and-const-kind",
    "pointerNotation": "json-pointer-with-*-for-array-elements",
    "sourceSpace": "resource.metadata.space",
    "crossSpace": "unrepresentable",
    "missingTarget": "resource_not_found/404-before-mutation",
    "wrongTargetForm": "invalid_argument/400-before-mutation",
    "storedResolution": "pointer+relation+targetApiVersion+targetKind+targetName+targetUid+bindingRef?",
    "targetIdentity": "uid-pinned; a-name-is-never-re-resolved-without-a-new-apply",
    "targetIncarnationChanged": "Ready=False/ExternalChange+hostReason",
    "targetGone": "Ready=False/DependencyMissing+hostReason",
    "referencedTargetDeletion": "dependency_in_use/409"
  },
  "bindingResolution": {
    "sourceSpace": "resource.metadata.space",
    "reference": "typed-binding-target-apiVersion-kind-and-name",
    "contractAnnotation": "desiredSchema-binding-list-property-x-takoform-binding",
    "crossSpace": "unrepresentable",
    "missing": "resource_not_found/404-before-mutation",
    "bindingNotAccepted": "invalid_argument/400-before-mutation",
    "contractNotInstalled": "unsupported_capability/422-before-mutation",
    "sourceRoleMismatch": "invalid_argument/400-before-mutation",
    "targetFormNotAllowed": "invalid_argument/400-before-mutation",
    "targetInterfaceNotProvided": "invalid_argument/400-before-mutation",
    "boundTargetDeletion": "dependency_in_use/409"
  },
  "artifactReference": {
    "desiredState": "bundle-shaped-revision-carries-the-manifest-digest-and-nothing-else",
    "resolution": "host-resolves-the-committed-manifest-before-mutation-on-apply-and-import",
    "uncommittedDigest": "artifact_missing/404-before-mutation",
    "digestMismatchOrUndecodable": "artifact_invalid/400-before-mutation",
    "kindMismatch": "artifact_invalid/400-before-mutation",
    "manifestContractViolation": "artifact_invalid/400-before-mutation",
    "perKindExclusivity": "WorkerBundle-carries-modules-not-files; StaticAssetBundle-and-MigrationBundle-carry-files-not-modules",
    "loadableModuleMediaTypes": "application/javascript+module, text/plain, application/octet-stream, application/wasm",
    "auxiliaryModuleMediaTypes": "application/source-map+json",
    "unsupportedModuleMediaTypes": "application/json",
    "mainModuleClass": "must-name-a-loadable-module; auxiliary-mainModule-is-artifact_invalid/400; carrying-an-auxiliary-module-is-never-an-error",
    "commitRevalidation": "every-manifest-rule-re-verified-at-commit",
    "retention": "committed-manifest-and-blobs-readable-while-any-resource-references-them"
  },
  "attachmentClaims": {
    "hostnameCanonicalization": "trailing-root-dot-removed-and-ascii-lowercased-at-the-materialization-entry-point-before-validation-digesting-storage-and-echo",
    "hostnameInternationalization": "a-label-only; the-form-pattern-admits-no-non-ascii-byte-and-a-host-performs-no-idna-mapping",
    "hostnameUniqueness": "one-canonical-hostname-per-tenant-across-every-space; second-claim-is-invalid_argument/400-before-mutation",
    "deadLetterAcyclicity": "a-dead-letter-reference-resolving-to-the-consumers-own-queue-or-closing-a-cycle-of-any-length-is-invalid_argument/400-before-mutation",
    "commitRevalidation": "both-claims-re-verified-when-an-accepted-202-commits"
  },
  "adoption": {
    "nativeId": "host-detail; required-on-import; never-echoed-in-any-response",
    "recordedOn": "the-resource-the-adoption-mints-or-addresses",
    "exclusivity": "one-live-resource-per-native-identity-per-tenant-across-every-space; second-claim-is-import_conflict/409-before-mutation",
    "claimImmutability": "an-import-addressing-an-existing-resource-under-another-nativeId-is-import_conflict/409-before-mutation; re-importing-under-the-recorded-one-answers-the-same-incarnation",
    "claimRelease": "released-when-the-resource-holding-it-is-deleted",
    "crossTenant": "not-a-conflict; a-host-wide-claim-would-disclose-another-tenants-holdings"
  },
  "roleRules": {
    "revisionUpdate": "invalid_argument",
    "attachmentDeleteCascade": "never-deletes-parent",
    "deploymentTrafficAuthority": "deployment-role-only"
  },
  "capabilityRules": {
    "baseCapabilities": ["create", "read", "delete", "import", "observe"],
    "updateCapability": "declared-only-when-the-Form-has-a-mutable-desired-field",
    "specChangeWithoutUpdateCapability": "invalid_argument-before-mutation"
  },
  "portableDefaults": {
    "carrier": "desiredSchema-properties-default",
    "materialization": "host-materializes-declared-defaults-at-the-entry-point-before-validation-and-digesting",
    "specDigest": "digest-of-the-materialized-spec",
    "clientObligation": "accept-the-materialized-echo",
    "servedContract": "the-form-definition-surface-serves-the-installed-Definitions-own-desiredSchema-at-the-exact-formRef; declared-defaults-bounds-patterns-and-enums-unchanged"
  },
  "operations": [
    {
      "name": "forms",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/forms",
      "exactFormQuery": true,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/formsResponse"
    },
    {
      "name": "form-definition",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/form-definitions/{formGroup}/{formVersion}/{kind}",
      "exactFormQuery": true,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/formDefinitionResponse"
    },
    {
      "name": "validate",
      "method": "POST",
      "path": "/apis/forms.takoform.com/v1beta1/resources/validate",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "requestSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/resourceRequest",
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/validateResponse"
    },
    {
      "name": "prepare",
      "method": "POST",
      "path": "/apis/forms.takoform.com/v1beta1/resources/prepare",
      "exactFormQuery": false,
      "precondition": "generation-fence-when-updating",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "requestSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/resourceRequest",
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/prepareResponse"
    },
    {
      "name": "apply",
      "method": "PUT",
      "path": "/apis/forms.takoform.com/v1beta1/resources/{formGroup}/{formVersion}/{kind}/{name}",
      "exactFormQuery": false,
      "precondition": "create:if-none-match-star update:generation-fence",
      "idempotencyKey": true,
      "mutates": true,
      "successStatus": [200, 201, 202],
      "requestSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/applyRequest",
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/mutationAccepted"
    },
    {
      "name": "read",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/resources/{formGroup}/{formVersion}/{kind}/{name}",
      "exactFormQuery": true,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/resourceResponse"
    },
    {
      "name": "import",
      "method": "POST",
      "path": "/apis/forms.takoform.com/v1beta1/resources/{formGroup}/{formVersion}/{kind}/{name}/import",
      "exactFormQuery": false,
      "precondition": "new:if-none-match-star existing:generation-fence",
      "idempotencyKey": true,
      "mutates": true,
      "successStatus": [200, 201, 202],
      "requestSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/importRequest",
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/mutationAccepted"
    },
    {
      "name": "observe",
      "method": "POST",
      "path": "/apis/forms.takoform.com/v1beta1/resources/{formGroup}/{formVersion}/{kind}/{name}/observe",
      "exactFormQuery": true,
      "precondition": "generation-fence",
      "idempotencyKey": true,
      "mutates": false,
      "successStatus": [200],
      "successGeneration": "equals-fence",
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/resourceEnvelope"
    },
    {
      "name": "delete",
      "method": "DELETE",
      "path": "/apis/forms.takoform.com/v1beta1/resources/{formGroup}/{formVersion}/{kind}/{name}",
      "exactFormQuery": true,
      "precondition": "generation-fence",
      "optionalPrecondition": "revision-fence",
      "idempotencyKey": true,
      "mutates": true,
      "successStatus": [202, 204]
    },
    {
      "name": "operation",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/operations/{id}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/operations/v1alpha1/operation.schema.json"
    },
    {
      "name": "operation-cancel",
      "method": "POST",
      "path": "/apis/forms.takoform.com/v1beta1/operations/{id}/cancel",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": true,
      "mutates": true,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/operations/v1alpha1/operation.schema.json"
    },
    {
      "name": "artifact-upload-start",
      "method": "POST",
      "path": "/apis/forms.takoform.com/v1beta1/artifacts/uploads",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": true,
      "mutates": true,
      "successStatus": [200, 201],
      "requestSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/artifactUploadRequest",
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/artifactUploadStatus"
    },
    {
      "name": "artifact-blob-upload",
      "method": "PUT",
      "path": "/apis/forms.takoform.com/v1beta1/artifacts/uploads/{uploadId}/blobs/{sha256}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": true,
      "successStatus": [201, 204]
    },
    {
      "name": "artifact-commit",
      "method": "POST",
      "path": "/apis/forms.takoform.com/v1beta1/artifacts/uploads/{uploadId}/commit",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": true,
      "mutates": true,
      "successStatus": [200, 201, 202],
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/artifactCommitResponse"
    },
    {
      "name": "artifact-manifest-read",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/artifacts/{manifestDigest}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/artifacts/v1alpha1/artifact-manifest.schema.json"
    },
    {
      "name": "artifact-blob-head",
      "method": "HEAD",
      "path": "/apis/forms.takoform.com/v1beta1/artifacts/blobs/{sha256}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200, 404]
    },
    {
      "name": "artifact-upload-abandon",
      "method": "DELETE",
      "path": "/apis/forms.takoform.com/v1beta1/artifacts/uploads/{uploadId}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": true,
      "mutates": true,
      "successStatus": [204]
    },
    {
      "name": "support-forms",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/support/forms",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/supportProfilesResponse"
    },
    {
      "name": "support-form",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/support/forms/{formGroup}/{formVersion}/{kind}/{definitionVersion}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/support/v1alpha1/host-support-profile.schema.json"
    },
    {
      "name": "support-interface",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/support/interfaces/{name}/{version}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/support/v1alpha1/host-support-profile.schema.json"
    },
    {
      "name": "support-binding",
      "method": "GET",
      "path": "/apis/forms.takoform.com/v1beta1/support/bindings/{name}/{version}",
      "exactFormQuery": false,
      "precondition": "none",
      "idempotencyKey": false,
      "mutates": false,
      "successStatus": [200],
      "responseSchema": "https://forms.takoform.com/schemas/support/v1alpha1/host-support-profile.schema.json"
    }
  ],
  "errorEnvelope": {
    "schema": "https://forms.takoform.com/schemas/v1beta1/host-api-wire.schema.json#/$defs/errorEnvelope",
    "codes": [
      "invalid_argument",
      "unauthenticated",
      "permission_denied",
      "form_unknown",
      "form_not_installed",
      "form_unavailable",
      "form_identity_conflict",
      "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",
      "deletion_protected",
      "artifact_missing",
      "artifact_invalid",
      "unsupported_capability",
      "migration_required",
      "uid_mismatch",
      "revision_conflict",
      "generation_conflict"
    ],
    "automaticallyRetryable": ["resource_busy", "backend_unavailable", "rate_limited", "deadline_exceeded"],
    "retryAfter": "honored-when-present-else-full-jitter-backoff",
    "httpStatusByCode": {
      "invalid_argument": 400,
      "unauthenticated": 401,
      "permission_denied": 403,
      "form_unknown": 404,
      "form_not_installed": 409,
      "form_unavailable": 409,
      "form_identity_conflict": 409,
      "resource_not_found": 404,
      "resource_busy": 409,
      "import_conflict": 409,
      "policy_denied": 403,
      "backend_unavailable": 503,
      "internal_error": 500,
      "rate_limited": 429,
      "deadline_exceeded": 504,
      "operation_cancelled": 409,
      "operation_not_found": 404,
      "dependency_in_use": 409,
      "deletion_protected": 409,
      "artifact_missing": 404,
      "artifact_invalid": 400,
      "unsupported_capability": 422,
      "migration_required": 409,
      "uid_mismatch": 409,
      "revision_conflict": 412,
      "generation_conflict": 412
    }
  }
}