--- title: Schema Reference description: "JSON-LD vocabulary for the Cetacean API: types, properties, and their IRIs." canonical: https://cetacean.mazetti.me/api/schema --- # Schema Reference Cetacean API responses include [JSON-LD](https://json-ld.org/) metadata (`@context`, `@id`, `@type`) for self-description. This page documents the vocabulary. The machine-readable context document is available at [/api/schema.jsonld](/api/schema.jsonld). ## Types Each API response includes an `@type` value identifying the resource kind. ### Collection A paginated list of resources. - endpoint: `All list endpoints` - properties: `items`, `total`, `limit`, `offset` ### Node A Docker Swarm node (manager or worker). - endpoint: `/nodes/{id}` - properties: `node`, `name`, `role`, `state`, `availability`, `tasks`, `services` ### Service A Docker Swarm service. - endpoint: `/services/{id}` - properties: `service`, `name`, `mode`, `replicas`, `image`, `ports`, `networks`, `aliases`, `tasks`, `updateStatus`, `state`, `changes`, `integrations` ### Task A single running or completed container instance. - endpoint: `/tasks/{id}` - properties: `task`, `state`, `slot`, `image`, `hostname` ### Stack A group of services deployed together via `com.docker.stack.namespace` labels. - endpoint: `/stacks/{name}` - properties: `stack`, `name`, `tasks` ### Config A Docker Swarm config object. - endpoint: `/configs/{id}` - properties: `config`, `name`, `services` ### Secret A Docker Swarm secret (data always redacted). - endpoint: `/secrets/{id}` - properties: `secret`, `name`, `services` ### Network A Docker network. - endpoint: `/networks/{id}` - properties: `network`, `name`, `driver`, `scope`, `services` ### Volume A Docker volume. - endpoint: `/volumes/{name}` - properties: `volume`, `name`, `driver`, `scope`, `services` ### Plugin An installed Docker plugin. - endpoint: `/plugins/{name}` - properties: `plugin`, `name` ### Cluster Cluster-wide overview with counts and resource totals. - endpoint: `/cluster` - properties: `nodeCount`, `serviceCount`, `taskCount`, `stackCount`, `nodesReady`, `nodesDown`, `nodesDraining`, `servicesConverged`, `servicesDegraded`, `reservedCPU`, `reservedMemory`, `totalCPU`, `totalMemory`, `tasksByState`, `prometheusConfigured` ### Swarm Swarm configuration: join tokens, Raft config, CA config. - endpoint: `/swarm` - properties: `managerAddr` ### ServiceEnv Service environment variables. - endpoint: `/services/{id}/env` - properties: `env` ### ServicePorts Service port bindings. - endpoint: `/services/{id}/ports` - properties: `ports` ### ServiceLabels Service labels. - endpoint: `/services/{id}/labels` - properties: `labels` ### ServiceResources Service CPU/memory reservations and limits. - endpoint: `/services/{id}/resources` - properties: `resources` ### ServicePlacement Service placement constraints and preferences. - endpoint: `/services/{id}/placement` - properties: `placement` ### ServiceUpdatePolicy Rolling update configuration for a service. - endpoint: `/services/{id}/update-policy` - properties: `updatePolicy` ### ServiceRollbackPolicy Rollback configuration for a service. - endpoint: `/services/{id}/rollback-policy` - properties: `rollbackPolicy` ### ServiceLogDriver Log driver configuration for a service. - endpoint: `/services/{id}/log-driver` - properties: `logDriver` ### ServiceHealthcheck Healthcheck configuration for a service. - endpoint: `/services/{id}/healthcheck` - properties: `healthcheck` ### ServiceConfigs Config references attached to a service. - endpoint: `/services/{id}/configs` - properties: `configs` ### ServiceSecrets Secret references attached to a service. - endpoint: `/services/{id}/secrets` - properties: `secrets` ### ServiceNetworks Network attachments for a service. - endpoint: `/services/{id}/networks` - properties: `networks` ### ServiceMounts Mount configuration for a service. - endpoint: `/services/{id}/mounts` - properties: `mounts` ### ServiceMode Service scheduling mode and replica count. - endpoint: `/services/{id}/mode` - properties: `mode`, `replicas` ### ServiceEndpointMode Service endpoint mode (vip or dnsrr). - endpoint: `/services/{id}/endpoint-mode` - properties: `endpointMode` ### NodeLabels Node labels. - endpoint: `/nodes/{id}/labels` - properties: `labels` ### NodeRole Node role in the swarm. - endpoint: `/nodes/{id}/role` - properties: `role`, `isLeader`, `managerCount` ### ClusterCapacity Cluster resource capacity: max single-node values and totals. - endpoint: `/cluster/capacity` - properties: `maxNodeCPU`, `maxNodeMemory`, `totalCPU`, `totalMemory`, `nodeCount` ### SearchResult Cross-resource search results. - endpoint: `/search` - properties: `query`, `results`, `counts`, `total` ### RecommendationCollection Cluster health recommendations from the recommendation engine. - endpoint: `/recommendations` - properties: `items`, `total`, `summary`, `computedAt` ### HistoryEntry A resource change event from the history ring buffer or SSE stream. - endpoint: `/history, /events` - properties: `kind`, `action`, `resourceId`, `timestamp`, `name` ### ServiceRef A cross-reference to a service (used in config/secret/network/volume detail responses). - endpoint: `Embedded in detail responses` - properties: `name` ### Health Health check response with build metadata and operations level. - endpoint: `/-/health` - properties: `version`, `commit`, `buildDate`, `operationsLevel` ### ProblemDetail An error response following RFC 9457 Problem Details. - endpoint: `Error responses` - properties: `type`, `title`, `status`, `detail`, `instance`, `requestId` ## Properties Properties are mapped to IRIs via the `@context`. The `urn:cetacean:` namespace is the default vocabulary; [RFC 9457](https://www.rfc-editor.org/info/rfc9457/) problem detail fields use `urn:ietf:rfc:9457#`. ### action The action performed on a resource (create, update, remove). - iri: `urn:cetacean:action` - type: `String` - used on: `HistoryEntry` ### aliases DNS aliases for a service on a given network. - iri: `urn:cetacean:aliases` - type: `Array of String` - used on: `Service` ### availability The scheduling availability of a node: `active`, `pause`, or `drain`. - iri: `urn:cetacean:availability` - type: `String` - used on: `Node` ### buildDate Build timestamp of the running binary. - iri: `urn:cetacean:buildDate` - type: `String` - used on: `Health` ### changes Spec changes from the previous service version. - iri: `urn:cetacean:changes` - type: `Array` - container: `@list` - used on: `Service` ### commit Git commit SHA of the build. - iri: `urn:cetacean:commit` - type: `String` - used on: `Health` ### computedAt Timestamp when recommendations were last computed. - iri: `urn:cetacean:computedAt` - type: `DateTime` - used on: `RecommendationCollection` ### config The Docker config object. - iri: `urn:cetacean:config` - type: `Object` - used on: `Config` ### configs Config references attached to a service. - iri: `urn:cetacean:configs` - type: `Array` - container: `@list` - used on: `ServiceConfigs` ### counts Result counts per resource type. - iri: `urn:cetacean:counts` - type: `Object` - used on: `SearchResult` ### detail A human-readable explanation specific to this occurrence (RFC 9457). - iri: `urn:ietf:rfc:9457#detail` - type: `String` - used on: `ProblemDetail` ### driver The driver backing a network or volume (e.g., `overlay`, `local`). - iri: `urn:cetacean:driver` - type: `String` - used on: `Network`, `Volume` ### endpointMode Endpoint mode for a service: `vip` or `dnsrr`. - iri: `urn:cetacean:endpointMode` - type: `String` - used on: `ServiceEndpointMode` ### env Environment variables as a key-value map. - iri: `urn:cetacean:env` - type: `Object` - used on: `ServiceEnv` ### healthcheck Container healthcheck configuration. - iri: `urn:cetacean:healthcheck` - type: `Object` - used on: `ServiceHealthcheck` ### hostname Node hostname in a task cross-reference. - iri: `urn:cetacean:hostname` - type: `String` - used on: `Task` ### image The container image reference (registry/name:tag@digest). - iri: `urn:cetacean:image` - type: `String` - used on: `Service`, `Task` ### instance A URI reference identifying the specific occurrence of the problem (RFC 9457). - iri: `urn:ietf:rfc:9457#instance` - type: `URI` - used on: `ProblemDetail` ### integrations Detected third-party integrations for a service. - iri: `urn:cetacean:integrations` - type: `Array` - container: `@list` - used on: `Service` ### isLeader Whether this manager node is the Raft leader. - iri: `urn:cetacean:isLeader` - type: `Boolean` - used on: `NodeRole` ### items The set of resources in a collection response. - iri: `urn:cetacean:items` - type: `Array` - container: `@set` - used on: `Collection`, `RecommendationCollection` ### kind The resource kind for history and SSE events (e.g., `service`, `node`). - iri: `urn:cetacean:kind` - type: `String` - used on: `HistoryEntry` ### labels Labels as a key-value map. - iri: `urn:cetacean:labels` - type: `Object` - used on: `ServiceLabels`, `NodeLabels` ### limit Page size limit for a collection response. - iri: `urn:cetacean:limit` - type: `Integer` - used on: `Collection` ### logDriver Log driver name and options. - iri: `urn:cetacean:logDriver` - type: `Object` - used on: `ServiceLogDriver` ### managerAddr Manager node address for remote Docker API access. - iri: `urn:cetacean:managerAddr` - type: `String` - used on: `Swarm` ### managerCount Total number of manager nodes in the swarm. - iri: `urn:cetacean:managerCount` - type: `Integer` - used on: `NodeRole` ### maxNodeCPU CPU capacity (nanoCPUs) of the largest node in the cluster. - iri: `urn:cetacean:maxNodeCPU` - type: `Integer` - used on: `ClusterCapacity` ### maxNodeMemory Memory capacity (bytes) of the largest node in the cluster. - iri: `urn:cetacean:maxNodeMemory` - type: `Integer` - used on: `ClusterCapacity` ### mode The scheduling mode of a service: `replicated` or `global`. - iri: `urn:cetacean:mode` - type: `String` - used on: `Service`, `ServiceMode` ### mounts Mount configuration attached to a service. - iri: `urn:cetacean:mounts` - type: `Array` - container: `@list` - used on: `ServiceMounts` ### name The human-readable name of a resource. For nodes this is the hostname; for services, configs, secrets, networks, and volumes it is the Docker object name. - iri: `urn:cetacean:name` - type: `String` - used on: `Node`, `Service`, `Stack`, `Config`, `Secret`, `Network`, `Volume`, `ServiceRef` ### network The Docker network object. - iri: `urn:cetacean:network` - type: `Object` - used on: `Network` ### networks The networks a service is attached to. - iri: `urn:cetacean:networks` - type: `Array of NetworkAttachment` - container: `@list` - used on: `Service`, `ServiceNetworks` ### node The Docker node object. - iri: `urn:cetacean:node` - type: `Object` - used on: `Node` ### nodeCount Number of nodes in the cluster. - iri: `urn:cetacean:nodeCount` - type: `Integer` - used on: `Cluster`, `ClusterCapacity` ### nodesDown Number of nodes in down state. - iri: `urn:cetacean:nodesDown` - type: `Integer` - used on: `Cluster` ### nodesDraining Number of nodes in drain state. - iri: `urn:cetacean:nodesDraining` - type: `Integer` - used on: `Cluster` ### nodesReady Number of nodes in ready state. - iri: `urn:cetacean:nodesReady` - type: `Integer` - used on: `Cluster` ### offset Page offset for a collection response. - iri: `urn:cetacean:offset` - type: `Integer` - used on: `Collection` ### operationsLevel Current operations level (0=read-only, 1=operational, 2=configuration, 3=impactful). - iri: `urn:cetacean:operationsLevel` - type: `Integer` - used on: `Health` ### placement Placement constraints and preferences for a service. - iri: `urn:cetacean:placement` - type: `Object` - used on: `ServicePlacement` ### plugin The Docker plugin object. - iri: `urn:cetacean:plugin` - type: `Object` - used on: `Plugin` ### ports Published port bindings for a service, ordered by target port. - iri: `urn:cetacean:ports` - type: `Array of PortConfig` - container: `@list` - used on: `Service`, `ServicePorts` ### prometheusConfigured Whether a Prometheus instance is configured. - iri: `urn:cetacean:prometheusConfigured` - type: `Boolean` - used on: `Cluster` ### query The search query string. - iri: `urn:cetacean:query` - type: `String` - used on: `SearchResult` ### replicas The configured number of replicas for a replicated service. - iri: `urn:cetacean:replicas` - type: `Integer` - used on: `Service`, `ServiceMode` ### requestId Unique request identifier for error correlation. - iri: `urn:cetacean:requestId` - type: `String` - used on: `ProblemDetail` ### reservedCPU Total reserved CPU (nanoCPUs) across all services. - iri: `urn:cetacean:reservedCPU` - type: `Integer` - used on: `Cluster` ### reservedMemory Total reserved memory (bytes) across all services. - iri: `urn:cetacean:reservedMemory` - type: `Integer` - used on: `Cluster` ### resourceId The ID of the affected resource. - iri: `urn:cetacean:resourceId` - type: `String` - used on: `HistoryEntry` ### resources CPU/memory reservations and limits for a service. - iri: `urn:cetacean:resources` - type: `Object` - used on: `ServiceResources` ### results Search results grouped by resource type. - iri: `urn:cetacean:results` - type: `Object` - used on: `SearchResult` ### role The role of a node in the swarm: `manager` or `worker`. - iri: `urn:cetacean:role` - type: `String` - used on: `Node`, `NodeRole` ### rollbackPolicy Rollback configuration for a service. - iri: `urn:cetacean:rollbackPolicy` - type: `Object` - used on: `ServiceRollbackPolicy` ### scope The scope of a network or volume: `swarm` or `local`. - iri: `urn:cetacean:scope` - type: `String` - used on: `Network`, `Volume` ### secret The Docker secret object (data always redacted). - iri: `urn:cetacean:secret` - type: `Object` - used on: `Secret` ### secrets Secret references attached to a service. - iri: `urn:cetacean:secrets` - type: `Array` - container: `@list` - used on: `ServiceSecrets` ### service The Docker service object. - iri: `urn:cetacean:service` - type: `Object` - used on: `Service` ### serviceCount Number of services in the cluster. - iri: `urn:cetacean:serviceCount` - type: `Integer` - used on: `Cluster` ### services Cross-referenced services using this resource. - iri: `urn:cetacean:services` - type: `Array of ServiceRef` - container: `@list` - used on: `Config`, `Secret`, `Network`, `Volume` ### servicesConverged Number of services with all tasks running. - iri: `urn:cetacean:servicesConverged` - type: `Integer` - used on: `Cluster` ### servicesDegraded Number of services with fewer tasks than desired. - iri: `urn:cetacean:servicesDegraded` - type: `Integer` - used on: `Cluster` ### slot The slot number of a task within a replicated service. Each replica occupies a unique slot. - iri: `urn:cetacean:slot` - type: `Integer` - used on: `Task` ### stack The stack detail with member resources. - iri: `urn:cetacean:stack` - type: `Object` - used on: `Stack` ### stackCount Number of stacks in the cluster. - iri: `urn:cetacean:stackCount` - type: `Integer` - used on: `Cluster` ### state The current state of a resource. For nodes: `ready`, `down`, or `unknown`. For tasks: `running`, `failed`, `complete`, etc. For services: a derived state based on running/desired task counts. - iri: `urn:cetacean:state` - type: `String` - used on: `Node`, `Service`, `Task` ### status The HTTP status code for the problem (RFC 9457). - iri: `urn:ietf:rfc:9457#status` - type: `Integer` - used on: `ProblemDetail` ### summary Severity summary (critical/warning/info counts). - iri: `urn:cetacean:summary` - type: `Object` - used on: `RecommendationCollection` ### task The Docker task object, enriched with ServiceName and NodeHostname. - iri: `urn:cetacean:task` - type: `Object` - used on: `Task` ### taskCount Number of tasks in the cluster. - iri: `urn:cetacean:taskCount` - type: `Integer` - used on: `Cluster` ### tasks The list of tasks belonging to a service or running on a node. - iri: `urn:cetacean:tasks` - type: `Array of Task` - container: `@list` - used on: `Service`, `Node`, `Stack` ### tasksByState Task counts grouped by state. - iri: `urn:cetacean:tasksByState` - type: `Object` - used on: `Cluster` ### timestamp When the event occurred. - iri: `urn:cetacean:timestamp` - type: `DateTime` - used on: `HistoryEntry` ### title A short human-readable summary of the problem type (RFC 9457). - iri: `urn:ietf:rfc:9457#title` - type: `String` - used on: `ProblemDetail` ### total Total count of items. - iri: `urn:cetacean:total` - type: `Integer` - used on: `Collection`, `SearchResult`, `RecommendationCollection` ### totalCPU Total cluster CPU capacity (nanoCPUs). - iri: `urn:cetacean:totalCPU` - type: `Integer` - used on: `Cluster`, `ClusterCapacity` ### totalMemory Total cluster memory capacity (bytes). - iri: `urn:cetacean:totalMemory` - type: `Integer` - used on: `Cluster`, `ClusterCapacity` ### type A URI reference identifying the problem type (RFC 9457). - iri: `urn:ietf:rfc:9457#type` - type: `URI` - used on: `ProblemDetail` ### updatePolicy Rolling update configuration for a service. - iri: `urn:cetacean:updatePolicy` - type: `Object` - used on: `ServiceUpdatePolicy` ### updateStatus The status of a rolling update for a service, if one is in progress. - iri: `urn:cetacean:updateStatus` - type: `UpdateStatus` - used on: `Service` ### version Software version string. - iri: `urn:cetacean:version` - type: `String` - used on: `Health` ### volume The Docker volume object. - iri: `urn:cetacean:volume` - type: `Object` - used on: `Volume`