Skip to content
🐋Cetacean

Schema Reference

Cetacean API responses include JSON-LD metadata (@context, @id, @type) for self-description. This page documents the vocabulary. The machine-readable context document is available at /api/schema.jsonld.

Types

Each API response includes an @type value identifying the resource kind.

Properties

Properties are mapped to IRIs via the @context. The urn:cetacean: namespace is the default vocabulary; RFC 9457 problem detail fields use urn:ietf:rfc:9457#.

  • action

    The action performed on a resource (create, update, remove).

  • aliases

    DNS aliases for a service on a given network.

    IRI
    urn:cetacean:aliases
    Type
    Array of String
    Used on
  • availability

    The scheduling availability of a node: active, pause, or drain.

    IRI
    urn:cetacean:availability
    Type
    String
    Used on
  • buildDate

    Build timestamp of the running binary.

    IRI
    urn:cetacean:buildDate
    Type
    String
    Used on
  • changes@list

    Spec changes from the previous service version.

    IRI
    urn:cetacean:changes
    Type
    Array
    Used on
  • commit

    Git commit SHA of the build.

    IRI
    urn:cetacean:commit
    Type
    String
    Used on
  • computedAt

    Timestamp when recommendations were last computed.

  • config

    The Docker config object.

    IRI
    urn:cetacean:config
    Type
    Object
    Used on
  • configs@list

    Config references attached to a service.

  • counts

    Result counts per resource type.

  • detail

    A human-readable explanation specific to this occurrence (RFC 9457).

  • driver

    The driver backing a network or volume (e.g., overlay, local).

  • endpointMode

    Endpoint mode for a service: vip or dnsrr.

  • env

    Environment variables as a key-value map.

  • healthcheck

    Container healthcheck configuration.

  • hostname

    Node hostname in a task cross-reference.

    IRI
    urn:cetacean:hostname
    Type
    String
    Used on
  • image

    The container image reference (registry/name:tag@digest).

  • instance

    A URI reference identifying the specific occurrence of the problem (RFC 9457).

  • integrations@list

    Detected third-party integrations for a service.

    IRI
    urn:cetacean:integrations
    Type
    Array
    Used on
  • isLeader

    Whether this manager node is the Raft leader.

    IRI
    urn:cetacean:isLeader
    Type
    Boolean
    Used on
  • items@set

    The set of resources in a collection response.

  • kind

    The resource kind for history and SSE events (e.g., service, node).

  • labels

    Labels as a key-value map.

  • limit

    Page size limit for a collection response.

  • logDriver

    Log driver name and options.

  • managerAddr

    Manager node address for remote Docker API access.

    IRI
    urn:cetacean:managerAddr
    Type
    String
    Used on
  • managerCount

    Total number of manager nodes in the swarm.

    IRI
    urn:cetacean:managerCount
    Type
    Integer
    Used on
  • maxNodeCPU

    CPU capacity (nanoCPUs) of the largest node in the cluster.

  • maxNodeMemory

    Memory capacity (bytes) of the largest node in the cluster.

  • mode

    The scheduling mode of a service: replicated or global.

  • mounts@list

    Mount configuration attached to a service.

  • 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.

  • network

    The Docker network object.

    IRI
    urn:cetacean:network
    Type
    Object
    Used on
  • networks@list

    The networks a service is attached to.

  • node

    The Docker node object.

    IRI
    urn:cetacean:node
    Type
    Object
    Used on
  • nodeCount

    Number of nodes in the cluster.

  • nodesDown

    Number of nodes in down state.

    IRI
    urn:cetacean:nodesDown
    Type
    Integer
    Used on
  • nodesDraining

    Number of nodes in drain state.

    IRI
    urn:cetacean:nodesDraining
    Type
    Integer
    Used on
  • nodesReady

    Number of nodes in ready state.

    IRI
    urn:cetacean:nodesReady
    Type
    Integer
    Used on
  • offset

    Page offset for a collection response.

    IRI
    urn:cetacean:offset
    Type
    Integer
    Used on
  • operationsLevel

    Current operations level (0=read-only, 1=operational, 2=configuration, 3=impactful).

    IRI
    urn:cetacean:operationsLevel
    Type
    Integer
    Used on
  • placement

    Placement constraints and preferences for a service.

  • plugin

    The Docker plugin object.

    IRI
    urn:cetacean:plugin
    Type
    Object
    Used on
  • ports@list

    Published port bindings for a service, ordered by target port.

  • prometheusConfigured

    Whether a Prometheus instance is configured.

    IRI
    urn:cetacean:prometheusConfigured
    Type
    Boolean
    Used on
  • query

    The search query string.

  • replicas

    The configured number of replicas for a replicated service.

  • requestId

    Unique request identifier for error correlation.

  • reservedCPU

    Total reserved CPU (nanoCPUs) across all services.

    IRI
    urn:cetacean:reservedCPU
    Type
    Integer
    Used on
  • reservedMemory

    Total reserved memory (bytes) across all services.

    IRI
    urn:cetacean:reservedMemory
    Type
    Integer
    Used on
  • resourceId

    The ID of the affected resource.

  • resources

    CPU/memory reservations and limits for a service.

  • results

    Search results grouped by resource type.

  • role

    The role of a node in the swarm: manager or worker.

  • rollbackPolicy

    Rollback configuration for a service.

  • scope

    The scope of a network or volume: swarm or local.

  • secret

    The Docker secret object (data always redacted).

    IRI
    urn:cetacean:secret
    Type
    Object
    Used on
  • secrets@list

    Secret references attached to a service.

  • service

    The Docker service object.

    IRI
    urn:cetacean:service
    Type
    Object
    Used on
  • serviceCount

    Number of services in the cluster.

    IRI
    urn:cetacean:serviceCount
    Type
    Integer
    Used on
  • services@list

    Cross-referenced services using this resource.

  • servicesConverged

    Number of services with all tasks running.

    IRI
    urn:cetacean:servicesConverged
    Type
    Integer
    Used on
  • servicesDegraded

    Number of services with fewer tasks than desired.

    IRI
    urn:cetacean:servicesDegraded
    Type
    Integer
    Used on
  • 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
  • stack

    The stack detail with member resources.

    IRI
    urn:cetacean:stack
    Type
    Object
    Used on
  • stackCount

    Number of stacks in the cluster.

    IRI
    urn:cetacean:stackCount
    Type
    Integer
    Used on
  • 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.

  • status

    The HTTP status code for the problem (RFC 9457).

  • summary

    Severity summary (critical/warning/info counts).

  • task

    The Docker task object, enriched with ServiceName and NodeHostname.

    IRI
    urn:cetacean:task
    Type
    Object
    Used on
  • taskCount

    Number of tasks in the cluster.

    IRI
    urn:cetacean:taskCount
    Type
    Integer
    Used on
  • tasks@list

    The list of tasks belonging to a service or running on a node.

  • tasksByState

    Task counts grouped by state.

    IRI
    urn:cetacean:tasksByState
    Type
    Object
    Used on
  • timestamp

    When the event occurred.

  • title

    A short human-readable summary of the problem type (RFC 9457).

  • total

    Total count of items.

  • totalCPU

    Total cluster CPU capacity (nanoCPUs).

  • totalMemory

    Total cluster memory capacity (bytes).

  • type

    A URI reference identifying the problem type (RFC 9457).

  • updatePolicy

    Rolling update configuration for a service.

  • updateStatus

    The status of a rolling update for a service, if one is in progress.

    IRI
    urn:cetacean:updateStatus
    Type
    UpdateStatus
    Used on
  • version

    Software version string.

    IRI
    urn:cetacean:version
    Type
    String
    Used on
  • volume

    The Docker volume object.

    IRI
    urn:cetacean:volume
    Type
    Object
    Used on