| name | indykite-data-schema |
| description | Read the observed data schema of the IndyKite Knowledge Graph (IKG) via the Data Schema REST API (`GET /data-schema/v1/`) - a JGFv2 document listing every node type with its properties, value-type tallies, and labels, plus every (source, relation, target) relationship combination, with occurrence counts but never the data itself. Use before authoring Cypher for CIQ Knowledge Queries or KBAC policies (exact type and property spellings), to verify a Capture ingest landed, to detect schema drift, or to give an agent the graph's vocabulary - "what does our IKG look like?". Not for reading graph data (indykite-ciq-read), writing it (indykite-capture-* / indykite-ciq-*), or authoring policies (indykite-authzen-kbac-policies). |
| license | Apache-2.0 |
| compatibility | Requires curl, bash 4+, and jq. Network access to the regional IndyKite REST API (eu.api.indykite.com or us.api.indykite.com) is required at runtime. |
IndyKite Data Schema - read the IKG's observed schema
The IndyKite Knowledge Graph (IKG) has no up-front schema definition step: the schema emerges from the data ingested through the Capture API or ContX IQ upserts. The platform tracks that emergent schema - which node types exist, which properties they carry with which value types, and how the types are connected - and exposes it through the Data Schema API as a JSON Graph Format (JGF) v2 document.
It is a schema-level view only: type names, property names, observed value types, and occurrence counts. It never returns the data itself, so it is safe to hand to tools and agents that should know the graph's vocabulary without seeing its contents.
When to use
Activate this skill when the user wants to:
- discover the exact spelling of node types, relationship types, and property names before authoring Cypher - a CIQ policy or Knowledge Query (
indykite-ciq-read and siblings) or a KBAC policy (indykite-authzen-kbac-policies) references them literally, and a policy written against givenName matches nothing when the data was ingested as given_name;
- verify an ingest - after a Capture batch, one GET confirms the expected types and properties landed and the counts sanity-check the volume (a
"Perosn" typo shows up immediately as a surprise node type);
- detect schema drift or data-quality issues - a property reporting
string: 4980, integer: 20 means an upstream source started sending the wrong type;
- get a meta-model overview of the project's graph ("what does our IKG look like?") for onboarding, visualization, or impact analysis before a cleanup.
Do not activate this skill when the user:
- wants the data itself - that is a ContX IQ read (
indykite-ciq-read);
- wants to write nodes, relationships, or properties (the
indykite-capture-* and indykite-ciq-* skills);
- expects to define or enforce a schema - the response is descriptive, observed from ingested data; it is not a constraint definition you author.
Prerequisites
- An IndyKite project with an AppAgent and AppAgent credentials (the token that goes into
X-IK-ClientKey) - see the Credentials guide.
- Data already ingested. A project with an empty IKG returns
404 Not Found - that is the normal "nothing ingested yet" answer, not a failure of this skill.
Steps
1. Call the endpoint
GET <API_URL>/data-schema/v1/
where API_URL is https://eu.api.indykite.com or https://us.api.indykite.com, matching the project's region. Authentication is the AppAgent credential in the X-IK-ClientKey header, as is, without any prefix. There are no parameters - the project is derived from the credential.
A runnable shell helper builds the authenticated request: scripts/read-schema.sh — run with --print to preview the curl (host-pinned; token redacted).
2. Read the response
The response is one graph object:
graph.directed - always true.graph.metadata - created_at and updated_at timestamps of the schema.graph.nodes - a map keyed by node type. Each entry's metadata holds node_count, a properties map (keyed by property name), system_labels, and user_defined_labels (each a list of { name, count }).graph.edges - one entry per (source type, relation, target type) combination: the source and target node types, the relation (relationship type), directed, and metadata with the edge count and its properties map.
Each properties entry describes one property: how many times it occurs (count) and the observed value types with per-type tallies (types); node properties additionally carry a metadata map with the same statistics for their provenance fields. Trimmed example - one node type and one edge from a vehicle-rental graph:
{
"graph": {
"nodes": {
"Car": {
"metadata": {
"node_count": 1,
"properties": {
"manufacturer": { "count": 1, "types": [ { "type": "string", "count": 1 } ] },
"seats": { "count": 1, "types": [ { "type": "integer", "count":
The full field reference, a complete example response, and jq recipes for common questions ("which node types exist?", "which properties does Person have?") are in references/data-schema-reference.md.
3. Use what it tells you
- Copy spellings, don't retype them. Take node types, relationship types, and property names verbatim from the response into Cypher patterns, KBAC conditions, Capture payloads, and AuthZEN
subject.type / resource.type fields.
- Check the edge direction.
graph.edges records the stored source → target direction; a Cypher pattern drawn in the opposite direction matches nothing.
- Treat mixed type tallies as a red flag. More than one entry in a property's
types list usually means an upstream source changed what it sends.
- Diff over time.
graph.metadata.updated_at tells you when the schema last changed; polling and diffing the response is a cheap monitor for upstream changes.
- Count before you delete. The per-property and per-edge counts show how much data a cleanup would touch before you call the Capture delete endpoints.
Outcome
When this skill has been applied successfully:
GET /data-schema/v1/ returns the project's observed schema as a JGFv2 graph document - node types with property and label statistics, and one edges entry per (source, relation, target) combination - or a 404 that correctly identifies an empty project.- Downstream Cypher (CIQ policies and Knowledge Queries, KBAC conditions) and Capture payloads use type and property spellings taken from the response instead of guesses.
Files in this skill
Agent-specific notes
This skill uses generic markdown instructions and works across all agents listed in the README. The agent needs to be able to issue HTTP requests (curl or an HTTP client). No Claude Code hooks, Cursor @-mentions, or Copilot workspace context are required.
References
