GraphQL Schema Conventions

Rescile automatically generates a GraphQL schema based on the resources present in your graph.

Top-Level Fields

Every resource type (e.g., server, application, firewall_rule) is automatically exposed as a top-level query field.

Stable Schema (Empty Collections)

By default, Rescile operates with a stable GraphQL schema (--stable-schema, enabled by default in serve). Every resource type declared in a bound central schema is registered as a top-level query root field even when zero instances of that resource currently exist in the in-memory graph.

When queried, an empty collection returns an empty list [] rather than removing the query field from the GraphQL schema:

query EmptyCollectionSafe {
  # If no source_artifact nodes exist, returns [] instead of GraphQL schema error
  source_artifact {
    _empty
  }
}

This prevents front-end dashboards, portals, and client applications from failing with Unknown field "<type>" on type "Query" when an upstream extraction or model generates no instances. To disable this and omit empty types dynamically, run rescile-ce serve --no-stable-schema.

Arguments

filter: Filter resources by exact property match (e.g., server(filter: { environment: "prod" })).

Return Structure

When traversing a relationship (edge), the response structure is split into two objects to capture edge-metadata:

node: The properties of the target resource itself.
properties: The properties of the edge (relationship), including relation (edge type) and any declared edge properties.

Edge property types are inferred from the actual graph data and merged with any property_schema declared for the relation in a bound central schema. This means an *EdgeProperties type will expose schema-declared fields even when no matching edge instance currently exists in the graph.

Special Fields

__typename: Standard GraphQL field returning the resource type label.
graphJson: A top-level query that returns the entire underlying graph as a raw JSON string.
countNodes: A top-level query returning the total number of nodes in the graph.

The `JSON` Scalar

If a resource has a complex nested object imported “as is” (via the json! directive), it is exposed as a custom JSON scalar type.

This bypasses standard GraphQL strict object typing, allowing arbitrary nested data without enforcing a fixed schema schema or sanitizing characters.

GraphQL Schema Reference