/collections-development

name: collections-development
description: Design JSON Schema collections and CRUD patterns for Falcon Foundry apps. TRIGGER when user asks to "create a collection", "define a JSON schema", "store data in Foundry", runs `foundry collections create`, or needs help with indexable fields, FQL queries, or collection access patterns. DO NOT TRIGGER for workflow YAML, function handlers, or UI components — use the appropriate sub-skill.
version: 1.7.1
updated: 2026-11-10
tags: [foundry, collections, json-schema, nosql]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: data

Foundry Collections Development

> **Part of a suite.** If `development-workflow` has not already run, and this is a new app or its first capability, load the `development-workflow` skill first — it owns the CLI prerequisite check, scaffolding order, and manifest coordination.

Falcon Foundry Collections are NoSQL document stores with JSON Schema validation. They provide persistent storage for app data with CRUD operations, FQL queries, and schema enforcement.

Collection Naming Constraints

| Constraint | Rule | |-----------|------| | Length | 5-200 characters | | Start/end | Must begin and end with a letter or number | | Special characters | Only underscores (`_`) allowed — no hyphens, spaces, or other chars | | Case | Case-sensitive |

Collection Description Constraints

| Constraint | Rule | |-----------|------| | Length | 3-500 characters | | Start | Must begin with an alphanumeric character | | Allowed characters | Letters, numbers, spaces, dashes, periods, parentheses, and underscores only | | Not allowed | Commas, colons, semicolons, quotes, slashes, or other special characters |

**Check the description against this table before running `collections create`.** The CLI accepts a comma (or any other disallowed character) in `--description` without complaint; the rejection only surfaces later, from `foundry apps validate` or deploy, by which time the collection is already in the manifest and has to be fixed by hand. Write the description with letters, numbers, spaces, dashes, periods, parentheses, and underscores only.

Collection Limits

| Resource | Limit | |----------|-------| | Single object size | ~50 MB | | Schema size | 256 KB | | Object key length | 1-1,000 characters | | Indexed fields per schema | 10 | | Objects per collection | No enforced limit | | Collections per app | No enforced limit | | Search results per page | 500 max (default 50) |

JSON Schema Requirements

• **JSON Schema draft 7 only** — newer drafts (`draft/2020-12`, `draft/2019-09`) fail validation
• Schema is auto-versioned: v1.0 on creation, auto-incremented on modification
• `additionalProperties: false` by default — extra fields leak internal data and break type safety. Exception: a collection written with `custom_storage_object_key` whose fields may grow. Schema changes may not reach it after creation (see Common Pitfalls), so ship `true` there
• `x-cs-indexable: true` on individual properties for searchable fields (max 10 per collection)

CLI Scaffolding

# Write schema to /tmp/ first — the CLI copies it into collections/
foundry collections create \
  --name "my_collection" \
  --schema /tmp/schema.json \
  --description "App data store" \
  --no-prompt \
  --wf-expose \
  --wf-tags "tag1,tag2"

This creates the collection directory, copies the schema, and updates `manifest.yml`. Edit the project copy at `collections/my_collection.json` afterward to refine.

Exposing a Collection as an Agent Tool

Add `--agent-tools-expose` to let a Foundry AI agent read and write the collection:

foundry collections create --name "triage_notes" --schema /tmp/schema.json \
  --description "Agent triage notes" --agent-tools-expose --no-prompt

That writes one block onto the collection's manifest entry:

collections:
    - name: triage_notes
      agent_tools_integration:
        exposed: true

Exposure is only half the wiring. The agent must also name each operation it may call in its own `tools` list, using `action:collections.<collection_name>.<Operation>`. Without the `action:` prefix, the deploy fails with a bare `500`:

ai:
    agents:
        - name: Detection Triage Agent
          tools:
            - action:collections.triage_notes.CreateObject
            - action:collections.triage_notes.SearchObjects

Valid operations, exact casing required: `CreateObject`, `GetObject`, `DeleteObject`, `ListObjects`, `SearchObjects`.

A collection exposed but not listed in `tools` is unreachable by the agent, and vice versa — neither case produces an error, just an agent that silently cannot use the data. `agent_tools_integration` is independent of `workflow_integration`; a collection can be exposed to agents, to Fusion, to both, or to neither.

Agents can also use the generic collection, `action:mcp/gce/collections:collections:generic:<Operation>` — a scratch collection the platform creates per agent at runtime, needing no collection of your own. Use a named app collection when the data must outlive the agent or be readable by other capabilities. See `ai-agents-development`.

Collection API Access

Collections are managed via the CrowdStrike API or the `foundry-js` SDK. There are no CLI commands for reading/writing collection data, and collections can only be deleted from the Falcon Foundry UI (not the CLI).

PUT    /customobjects/v1/collections/{collection_name}/objects/{key}  — Create/update object
GET    /customobjects/v1/collections/{collection_name}/objects/{key}  — Get object by key
DELETE /customobjects/v1/collections/{collection_name}/objects/{key}  — Delete object
POST   /customobjects/v1/collections/{collection_name}/objects        — Search objects (FQL filter)

JSON Schema Patterns

Basic Schema

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Incident",
  "description