ak.schema.service_describe.v1

Arkret Service Describe

ak.schema.service_describe.v1 · file: schemas/service-describe.schema.json

Canonical role-scoped ServiceDescribe response. Runtime operation availability is the union of registered supported_operation_bundles intersected with usable transport_bindings; supported_features is the sole feature claim set. Profile claims remain conformance evidence and never add operations. Exact source-tree, generated-registry, SDK, service-build, or release-artifact fingerprints are not compatibility carriers and MUST remain outside this document and all protocol decisions.

* $ · object

anyOf · anyOf[0] · ?

anyOf · anyOf[1] · ?

allOf · allOf[0] · ?

allOf · allOf[1] · ?

allOf · allOf[2] · ?

allOf · allOf[3] · ?

allOf · allOf[4] · ?

allOf · allOf[5] · ?

* service_id · string · $ref ./common-ids.schema.json#/$defs/did_core_id

Canonical stable DID-derived identity core. The lowercase DID method name follows ak:did_core:, and the remaining method-adapter-defined core is opaque to generic consumers. The did:web v1 adapter uses the complete canonical method-specific-id, never a digest or truncated host. Principal-core and service-core equality is byte-for-byte equality of the complete did_core_id. Event actor and Realm membership equality instead use the complete closed ActorId, and account-scoped equality uses the complete AccountId; neither may be reduced to a principal core. A did_core_id is not a DID and cannot be resolved without a did or AuthenticatedServiceResolution.

pattern: ^ak:did_core:[a-z0-9]+:[^\s/?#]+$

* service_resolution · object · $ref ./identity-resolution.schema.json#/$defs/resolution_commitment

Owner-committed current did and method-native history position. For a deterministic method, method_history_head and version_id use the adapter-defined deterministic canonical values; they are never omitted.

* did · string · $ref ./common-ids.schema.json#/$defs/did

Canonical bare DID used for registration, DID method resolution and owner-published current resolution. It contains no path, query or fragment and MUST project through the registered method adapter to exactly one did_core_id.

pattern: ^did:[a-z0-9]+:[^\s/?#]+$

* method_history_head · string

* version_id · string

pattern: ^(?!ak:)

* trust_domain · string · $ref #/$defs/trust_domain

Deployment-scope trust domain for this service. Receivers use it as the canonical receive-context replay boundary for cross-deployment proofs and federation transactions.

pattern: ^ak:trust_domain:[a-z0-9][a-z0-9._\-:]{0,127}$

* service_kind · string (enum)

One logical role this service plays on the wire. Each ServiceDescribe document describes exactly one role; co-located roles sharing a public binding use separate role-scoped responses selected by GET /_arkret/describe?service_kind=<registered-id>. The value space is registry/service-kind-registry.json filtered to active rows whose valid_in contains service_describe.

enum: "agent_runtime" "applet_service" "archive_node" "blob_node" "directory_service" "identity_registry" "key_recovery_service" "media_service" "moderation_service" "station" "push_gateway" "recovery_service" "sfu_service" "turn_service"

* protocol_version · const "1.0"

Arkret protocol-family bootstrap discriminator. A consumer first extracts this field before applying the version-specific ServiceDescribe schema: a well-formed value other than 1.0 yields unsupported_protocol_version, while missing or non-string values yield schema_violation. The const keeps an object admitted as ak.schema.service_describe.v1 closed to Arkret/1.

enum: "1.0"

* supported_profiles · array<string>

The sole complete-profile self-declaration for this exact build and role endpoint. Every declared profile MUST satisfy its full applicable contract. Feature-only support belongs in supported_features. verified_profiles supplies independent evidence, never an alternate activation set; each verified profile MUST also occur here.

items · string

pattern: ^ak\.profile\.[a-z0-9][a-z0-9_.-]*\.v[0-9]+$

profile_bindings · object

Profile-specific carrier declarations keyed by profile id. A profile that mandates one interoperable private carrier must bind it here rather than relying on a product-local route.

* supported_features · array<string>

Canonical-sorted exact registered feature ids this role endpoint currently supports. This is the sole public runtime feature claim set.

items · string

pattern: ^ak\.feature\.[a-z0-9_]+(?:\.[a-z0-9_]+)*\.v1$

calendar_tzdb_versions · array<string>

IANA TZDB release tags this service can execute for calendar schedules, taken from calendar-timezone-registry.json. Required when the service claims a calendar profile. A schedule whose signed tzdb_version is absent here MUST fail closed with calendar_tzdb_mismatch or project its instants as unresolved; the service MUST NOT fall back to a nearby or newer release.

items · string

pattern: ^[0-9]{4}[a-z]$

* auth_metadata · object

Authentication and session metadata needed by clients before calling protected operations. Unregistered keys are limited to safely ignorable x_* metadata.

account_authority · object · $ref #/$defs/account_authority

* origin · allOf[1]

Absolute origin of the client-visible Account Authority.

allOf · allOf[0] · string (uri) · format=uri · $ref ./common-ids.schema.json#/$defs/web_origin

Canonical HTTP(S) Web Origin: lowercase scheme/host plus an optional valid non-default effective port. Userinfo, path (including a trailing slash), query, fragment, explicit :80 on HTTP, and explicit :443 on HTTPS are forbidden.

pattern:

^(?:http://(?:\[[0-9A-Fa-f:.]+\]|[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)(?::(?!80$)(?:[1-9]|[1-9][0-9]{1,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|https://(?:\[[0-9A-Fa-f:.]+\]|[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)(?::(?!443$)(?:[1-9]|[1-9][0-9]{1,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?)$

* gate_account_base_url · string (uri) · format=uri

Absolute base URL from which all client-visible /_arkret/gate/account/* endpoints MUST be derived.

pattern: ^https://[^?#]+/_arkret/gate/account/?$

(^x_[a-z][a-z0-9_]{0,63}$) · any

methods · array<$ref #/$defs/auth_method>

Authentication methods offered for this principal/account surface. Methods describe proof providers, standard discovery, and the proof kind accepted by the Account Authority. Arkret gate/account routing is always derived from account_authority.

items · object · $ref #/$defs/auth_method

allOf · allOf[0] · ?

* method · string (enum)

enum: "oidc" "passkey" "device_pairing" "recovery_challenge" "gnap"

issuer_uri · string (uri) · format=uri

provider_uri · string (uri) · format=uri

openid_configuration_url · string (uri) · format=uri

pattern: ^https://

client_id · string

pattern: ^(?!ak:)

scopes · array<string>

items · string

* grant_exchange · object · $ref #/$defs/auth_grant_exchange

* kind · const "account_handoff"

Every advertised interactive authentication method terminates in the AccountHandoff exchange. For OIDC, authentication-handoffs is the unique authorization-code consumer; SessionGrant issue never consumes the code.

enum: "account_handoff"

(^x_[a-z][a-z0-9_]{0,63}$) · any

did_binding_methods · array<string (enum)>

session_dpop is the mandatory default SessionGrant presentation; session_http_signature is only an additional high-security body/transcript binding layer. did_http_signature denotes separately registered DID proofs and is never a SessionGrant fallback.

items · string (enum)

enum: "session_dpop" "session_http_signature" "did_http_signature"

(^x_[a-z][a-z0-9_]{0,63}$) · any

* limits · object

Operational limits such as body size, batch size, TTL, pagination or retention bounds.

* plaintext_visibility · object

Plaintext boundary declaration. Omission is not allowed: callers use this object to decide whether the service may be registered as plaintext-visible. An empty object means the service claims no plaintext classes; Realm plaintext_visible_services entries MUST match non-empty data_classes here.

data_classes · array<$ref #/$defs/plaintext_data_class>

Closed machine-checkable classes of plaintext or reversible derived content this service is implemented to receive.

items · string (enum) · $ref #/$defs/plaintext_data_class

enum: "message_content" "strand_content" "attachment_plaintext" "attachment_preview" "thumbnail" "full_text_index" "search_snippet" "embedding" "notification_summary" "inbox_preview" "media_plaintext" "derived_plaintext" "account_private_state" "profile_private_field" "rsvp_response"

max_visibility · string (enum)

Maximum plaintext visibility class the service claims it can receive. Omitted is treated as none unless data_classes is non-empty.

enum: "none" "derived_plaintext" "private_plaintext"

event_kinds · array<string>

items · string

payload_paths · array<string>

items · string

blob_purposes · array<string>

items · string

projection_outputs · array<string>

items · string

notes · string

(^x_[a-z][a-z0-9_]{0,63}$) · any

privacy_derivation · object

Machine-readable privacy-preserving identifier derivation claims. Secret material is never published here; only profile and epoch metadata needed for audit and rotation checks.

push_target_id_derivation · object

* derivation_profile · const "ak.push_target_id.hmac_sha256.v1"

enum: "ak.push_target_id.hmac_sha256.v1"

* secret_scope · const "per_service"

The HMAC salt/pepper is unique to this service context and MUST NOT be shared across Stations, organizations, or push routes.

enum: "per_service"

* salt_epoch_id · string

Opaque public epoch label for the active secret. This is not the secret salt value.

pattern: ^(?!ak:)

* salt_rotation_seconds · integer

input_binding · array<string (enum)>

items · string (enum)

enum: "recipient_id" "principal_id" "device_id" "push_route_id" "salt_epoch_id"

receive_policy_constraints · object · $ref ./invite-receive-policy.schema.json#/$defs/receive_policy_constraints

Deployment/admin upper bound applied to subject-private receive policies. The effective receive policy is the intersection of the subject policy and these constraints; constraints can only make a subject less reachable, never more reachable.

policy_version · string

applies_to · array<string (enum)>

Surfaces governed by the introduction-evidence and disclosure members of this constraint object: deployment_allowed_introduction_kinds, deployment_denied_introduction_kinds, the three *_max_behavior members, disclosure_max, and the handle domain, handle issuer, directory, source and DID method lists. Omitted means both invite_delivery and contact_request. new_source_quota is NOT filtered by this member and always applies to all three first-contact surfaces (identity/consent-model.md section 6.1.1). The enum stays closed at these two values because the identity/consent-model.md section 6.1.1 consent request surface carries no introduction evidence and takes no part in graded disclosure, so the filtered members have nothing to select on it.

items · string (enum)

enum: "invite_delivery" "contact_request"

deployment_allowed_introduction_kinds · array<$ref #/$defs/introduction_kind>

Maximum set of introduction evidence kinds this deployment permits. Omitted means no deployment-level kind cap.

items · $ref #/$defs/introduction_kind · $ref #/$defs/introduction_kind

deployment_denied_introduction_kinds · array<$ref #/$defs/introduction_kind>

items · $ref #/$defs/introduction_kind · $ref #/$defs/introduction_kind

handle_claim_max_behavior · $ref #/$defs/receive_behavior · $ref #/$defs/receive_behavior

Maximum behavior allowed for handle_claim evidence using the order drop < quarantine < notify.

explicit_address_max_behavior · $ref #/$defs/receive_behavior · $ref #/$defs/receive_behavior

Maximum behavior allowed for explicit_address evidence using the order drop < quarantine < notify.

unknown_invites_max_behavior · string (enum)

enum: "drop" "quarantine"

new_source_quota · object

Deployment ceiling and defaults for the per-holder new-source quota required by identity/consent-model.md section 6.1.1. Omitting the object does NOT disable the quota: every omitted member takes the specification default below, because the quota itself is a MUST. This object MUST NOT be filtered by applies_to: it is the threshold of the single holder admission chokepoint of section 6.1.1.3, where invite delivery, contact delivery and the identity/consent-model.md section 6.1.1 consent request share one ledger and one set of thresholds, so it applies to all three surfaces whatever applies_to says. Both windows are sliding and are evaluated against one server-internal seen-source ledger; the quota never becomes observable to the requester, whose outcome stays inside the existing opaque deferred equivalence class.

window_seconds · integer

Short sliding rate window in seconds. Specification default 86400.

default_new_sources_per_window · integer

Short-window admission count used when the subject publishes no override. Specification default 3.

max_new_sources_per_window · integer

Upper bound a subject may raise the short window to. Specification default 10. MUST be greater than or equal to default_new_sources_per_window.

retention_seconds · integer

Long sliding window in seconds. It is also the seen-source ledger retention period; the two are one parameter. Specification default 2592000. MUST be greater than or equal to window_seconds.

default_new_sources_per_retention · integer

Long-window distinct new-source count used when the subject publishes no override. Specification default 30.

max_new_sources_per_retention · integer

Upper bound a subject may raise the long window to. Specification default 200, anchored to the quarantine typed current result maxItems. MUST be greater than or equal to default_new_sources_per_retention.

disclosure_max · object

Deployment/admin upper bound on graded invite outcome disclosure. Each present tier caps the corresponding subject disclosure value using opaque < outcome; omitted tiers impose no additional deployment cap.

high_trust_max · $ref #/$defs/disclosure_level · $ref #/$defs/disclosure_level

discovery_trust_max · $ref #/$defs/disclosure_level · $ref #/$defs/disclosure_level

low_trust_max · $ref #/$defs/disclosure_level · $ref #/$defs/disclosure_level

allowed_handle_domains · array<$ref #/$defs/domain_name>

Deployment-level allowlist for handle domains accepted as handle_claim evidence. Empty means no handle domain is accepted.

items · $ref #/$defs/domain_name · $ref #/$defs/domain_name

trusted_handle_issuer_ids · array<$ref #/$defs/did_core_id>

items · $ref #/$defs/did_core_id · $ref #/$defs/did_core_id

trusted_directory_ids · array<$ref #/$defs/did_core_id>

items · $ref #/$defs/did_core_id · $ref #/$defs/did_core_id

trusted_source_ids · array<$ref #/$defs/did_core_id>

items · $ref #/$defs/did_core_id · $ref #/$defs/did_core_id

denied_source_ids · array<$ref #/$defs/did_core_id>

items · $ref #/$defs/did_core_id · $ref #/$defs/did_core_id

accepted_subject_did_methods · array<$ref #/$defs/did_method>

items · $ref #/$defs/did_method · $ref #/$defs/did_method

rate_limit_policy_id · string

Identifier for a cacheable, verifiable rate-limit policy object with the same minimum fields as rate_limit_policy. See zh/sync/api-conventions.md §8.

pattern: ^(?!ak:)

rate_limit_policy · object

Inline rate-limit policy. If the service can return rate_limited, entries[] MUST expose at least endpoint or operation_id, rate_limit_scope, a window/limit tuple or a retry hint; an empty entries[] explicitly means no predictable endpoint-level rate limit beyond generic abuse protection.

policy_version · string

entries · array<object>

items · object

endpoint · string

Closed endpoint selector: either an absolute HTTP(S) URL or an absolute-path endpoint on this service.

anyOf · anyOf[0] · ?

pattern: ^/

anyOf · anyOf[1] · ? · format=uri

pattern: ^https?://

operation_id · string

pattern: ^ak\.[a-z0-9][a-z0-9_.-]*$

rate_limit_scope · oneOf[2]

oneOf · oneOf[0] · string

oneOf · oneOf[1] · array<string>

items · string

window_seconds · integer

max_requests · integer

burst · integer

max_bytes · integer

max_events_per_batch · integer

max_body_bytes · integer

retry_after_ms · integer

backoff_hint · string

next_retry_at · string (date-time) · format=date-time · $ref ./time.schema.json#/$defs/timestamp

Canonical Arkret-owned absolute instant. UTC Z form with exactly three millisecond digits. Whole seconds MUST use .000Z; offsets, missing/finer fractions, lowercase separators, leap seconds, and invalid Gregorian calendar dates are forbidden. Shape validation by this pattern is supplemented by semantic date validation.

pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$

effective_at · string (date-time) · format=date-time · $ref ./time.schema.json#/$defs/timestamp

pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$

expires_at · string (date-time) · format=date-time · $ref ./time.schema.json#/$defs/timestamp

pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$

cache_ttl_seconds · integer

egress_network_policy · object

Coarse outbound-network policy for SSRF protection. Public describe MAY omit sensitive allowlist entries; authenticated operator describe MAY return the complete policy. Normative semantics are defined in zh/sync/api-conventions.md §11.2.

* version · integer

* private_network_default · string (enum)

enum: "deny" "deny_unless_explicit_exception"

* protected_purposes · array<string (enum)>

items · string (enum)

enum: "did_resolution" "federation" "media_fetch" "realm_state_snapshot_fetch" "webhook" "applet" "agent" "directory" "push"

denied_cidrs · array<$ref #/$defs/cidr>

items · string · $ref #/$defs/cidr

IPv4 or IPv6 CIDR string. Parsability and address-family semantics are enforced by the egress policy evaluator.

allowed_cidrs · array<$ref #/$defs/cidr>

items · string · $ref #/$defs/cidr

IPv4 or IPv6 CIDR string. Parsability and address-family semantics are enforced by the egress policy evaluator.

allowed_private_exceptions · array<object>

items · object

* purpose · string

service_id · string · $ref ./common-ids.schema.json#/$defs/did_core_id

pattern: ^ak:did_core:[a-z0-9]+:[^\s/?#]+$

trust_domain · string · $ref #/$defs/trust_domain

pattern: ^ak:trust_domain:[a-z0-9][a-z0-9._\-:]{0,127}$

* cidrs · array<$ref #/$defs/cidr>

items · string · $ref #/$defs/cidr

IPv4 or IPv6 CIDR string. Parsability and address-family semantics are enforced by the egress policy evaluator.

ports · array<integer>

items · integer

development_mode_only · boolean

* expires_at · string (date-time) · format=date-time · $ref #/$defs/timestamp

pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$

* dns_rebind_protection · boolean

* redirect_recheck · boolean

resource_kinds · array<$ref #/$defs/directory_resource_kind>

Directory-service resource classes indexed by ak.find.directory.read.describe.v1. Required when service_kind=directory_service.

items · string (enum) · $ref #/$defs/directory_resource_kind

enum: "realm" "organization" "actor" "applet" "handle"

* verified_profiles · array<object>

Profiles for which a Conformance Verifier run (conformance-suite.md §6.2) has produced a passing verification artifact. Each entry MUST identify the verification run, artifact hash, artifact retrieval reference, verifier DID, verifier signature, and verification timestamp. When the service is in `development_mode=true` this array MUST be empty. Each profile_id MUST occur in supported_profiles and be unique within verified_profiles; consumers MUST verify this relationship and applicable artifact evidence before displaying a verified badge. Evidence alone MUST NOT activate a profile.

items · object

* profile_id · string

pattern: ^ak\.profile\.[a-z0-9._-]+\.v[0-9]+$

* claim_kind · string (enum)

enum: "conformance_verified"

* verification_run_id · string

pattern: ^(?!ak:)

* artifact_digest · string

pattern: ^sha256:[0-9a-f]{64}$

* artifact_ref · string

URI or transparency-log reference from which the verification artifact can be fetched.

* verifier_id · string · $ref ./common-ids.schema.json#/$defs/did_core_id

pattern: ^ak:did_core:[a-z0-9]+:[^\s/?#]+$

* signature · string

Signature over profile_id, verification_run_id, artifact_digest, artifact_ref, verifier and timestamp.

* timestamp · string (date-time) · format=date-time · $ref ./time.schema.json#/$defs/timestamp

pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$

expires_at · string (date-time) · format=date-time · $ref ./time.schema.json#/$defs/timestamp

pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$

* interop_surfaces · array<object>

Surfaces this service exposes outside its claimed Arkret v1 conformance: bridged third-party protocols and delegated resolver postures. A service MUST NOT declare its own product-private route root here — a private API is neither a bridged foreign protocol nor a delegation, and declaring one would grant it a conformance-adjacent standing it does not have. The object is closed so such a declaration cannot be smuggled in through extension keys.

items · object

* name · string

* kind · string (enum)

matrix_passthrough / mimi_passthrough: bridged foreign protocol surface. delegated_resolver: a DID document / key-log surface served on behalf of a canonical authority this service does not claim to be (conformance-profiles.md §9). external_interop: any other non-Arkret interop surface. This list is exhaustive; product-private APIs have no member here.

enum: "matrix_passthrough" "mimi_passthrough" "delegated_resolver" "external_interop"

since · string

notes · string

* development_mode · boolean

Mirror of the service's development_mode flag. When true, `verified_profiles` MUST be empty.

* supported_operation_bundles · array<string>

Canonical-sorted registered bundle ids this role endpoint fully implements. The local registry expands each id to exact (operation_id,binding_kind) pairs; unknown ids never grant availability.

items · string

pattern: ^ak\.operation_bundle\.[a-z0-9_]+(?:\.[a-z0-9_]+)*\.v1$

* transport_bindings · array<$ref #/$defs/transport_binding>

Transport endpoints in descending server preference. Operation coverage is not repeated here and comes only from supported_operation_bundles.

items · oneOf[3] · $ref #/$defs/transport_binding

oneOf · oneOf[0] · object · $ref #/$defs/transport_binding_http_json

* kind · const "http_json"

enum: "http_json"

* base_url · string (uri) · format=uri

pattern: ^https://

* extension_profile_required · null

oneOf · oneOf[1] · object · $ref #/$defs/transport_binding_tus

* kind · const "tus"

enum: "tus"

* base_url · string (uri) · format=uri

pattern: ^https://

* extension_profile_required · null

* tus_version · array<const "1.0.0">

items · const "1.0.0"

enum: "1.0.0"

* tus_extensions · array<string (enum)>

items · string (enum)

enum: "creation" "creation-with-upload" "checksum" "expiration" "termination"

oneOf · oneOf[2] · object · $ref #/$defs/transport_binding_websocket

WebSocket transport descriptor. kind=websocket fixes the required binding profile ak.profile.binding.websocket.v1, the arkret.v1 subprotocol and the challenge_dpop_session_v1 authentication through binding-kind-registry and the profile itself; the descriptor carries only the connection coordinates and transport limits.

* kind · const "websocket"

enum: "websocket"

* base_url · string (uri) · format=uri

pattern: ^wss://[a-z0-9.-]+(?::[1-9][0-9]{0,4})?/(?:[A-Za-z0-9._~!$&'()*+,;=:@/-]|%[0-9A-F]{2})*$

allOf · allOf[0] · ?

allOf · allOf[1] · ?

allOf · allOf[2] · ?

* max_frame_bytes · integer

* max_channels · integer

invite_addressing · object

Registered invite-addressing negotiation. Required when ak.feature.invite_addressing.v1 is advertised.

* supported_introduction_kinds · array<string (enum)>

items · string (enum)

enum: "locator_ref" "consent_grant" "shared_realm" "handle_claim" "same_station" "explicit_address"

* handle_claim_max_behavior · string (enum)

enum: "drop" "quarantine" "notify"

* explicit_address_max_behavior · string (enum)

enum: "drop" "quarantine" "notify"

(^x_[a-z][a-z0-9_]{0,63}$) · any

Source

registry row: spec/v1/artifacts/registry/schema-registry.json
schema document: spec/v1/artifacts/schemas/service-describe.schema.json