Package manifest structure
The package manifest (.c3pkg.json) is the only required file in a C3 AI package. It defines essential package metadata including name, version, author, and dependencies. The C3 Agentic AI Platform validates the manifest file to ensure packages are properly configured before deployment.
Manifest file location
The manifest file must be:
- Named exactly as
{packageName}.c3pkg.json - Located at the root of the package directory
- Use the exact package name in the filename
Example: For a package named myApp, the manifest file must be myApp/myApp.c3pkg.json.
Minimal manifest
At minimum, a valid manifest requires a package name and version:
{
"name": "myApp",
"version": "1.0.0"
}However, production packages typically include additional metadata:
{
"name": "myApp",
"description": "My application",
"author": "C3 AI",
"version": "1.0.0",
"dependencies": {
"platform": "8.4"
}
}Manifest fields reference
See a reference of the available fields. The fields are further described in Pkg.Decl.
| Field | Required | Type | Description | Example | Rules/Notes |
|---|---|---|---|---|---|
name | Yes | string | Package name - must be globally unique | "myApp" | Must match directory name exactly (case-sensitive). Must match manifest filename. Cannot contain spaces or special characters except underscores. Use camelCase by convention. |
version | Yes | string | Package version following semantic versioning | "1.0.0" | Format: MAJOR.MINOR.PATCH or MAJOR.MINOR. MAJOR = incompatible API changes, MINOR = backward-compatible functionality, PATCH = backward-compatible bug fixes. |
description | No | string | Human-readable package description | "Customer relationship management application" | Brief, one-sentence description. Appears in package listings and documentation. |
author | No | string | Package creator or maintainer | "C3 AI" | Organization or individual name. |
icon | No | string | Link to package icon image file | "assets/icon.png" | Path to icon file for package visual identification. |
dependencies | No | object | Other packages this package depends on with version constraints | {"platform": "8.6", "foundation": "1.2"} | Key = package name, Value = SemanticVersion.MajorMinor constraint. Use Major.Minor format (recommended). All dependencies must be available and resolvable. Order matters for remix precedence. |
compatibleToVersion | No | string | Version up to which this package promises backward compatibility | "1.2" | If another package depends on this version or later, this implementation promises API compatibility. Major.Minor format only. Enables flexible dependency resolution. |
dbDomain | No | string | Database domain if entity types belong to specific Db.Domain | "analytics" | Associates package entity types with a specific database domain. |
testRunnerConfig | No | object | Default TestRunnerConfig for package tests | {"timeout": 300} | Used by TestRunner.testPackage when no config explicitly passed. |
eslintConfig | No | object | ESLint configuration for package JavaScript/TypeScript | {"extends": ["standard"]} | Equivalent to .eslintrc contents. Preferred over separate file for MetadataStore persistence. |
codeGen | No | array | Code generation kinds required by this package | ["Java", "React", "Type"] | Valid values: "Col", "Java", "Js", "Poly", "Py", "React", "StdLib", "Type". Must match code generator class name prefix. |
main | No | string | Entry point Type for the package | "MyApp" | Specifies which Type serves as the package entry point. |
exports | No | array | Types exported for other packages to use | ["User", "Role"] | Explicitly declares which Types are part of the public API. |
license | No | string | Package license information | "Proprietary" | Common values: "Proprietary", "MIT", "Apache-2.0". |
repository | No | object | Source code repository information | {"type": "git", "url": "https://..."} | Includes repository type and URL for source code location. |
keywords | No | array | Search keywords for package discovery | ["crm", "customer"] | Helps others discover your package in package listings. |
fromJava | No | array | Java-related configuration | ["com.example.package"] | Internal field for Java package mapping. |
area | No | array | Package categorization areas | ["sales", "marketing"] | Organizational categorization for package grouping. |
Complete manifest example
A fully-featured manifest with all common fields:
{
"name": "customerApp",
"version": "2.1.0",
"description": "Customer relationship management application",
"author": "C3 AI",
"license": "Proprietary",
"main": "CustomerApp",
"keywords": ["crm", "customer", "sales"],
"repository": {
"type": "git",
"url": "https://github.com/c3ai/customer-app"
},
"dependencies": {
"platform": "8.4",
"uiComponentLibrary": "1.0",
"genaiPlatform": "1.2"
},
"exports": [
"Customer",
"Account",
"Opportunity",
"Contact"
]
}Validation rules
The C3 Agentic AI Platform validates the manifest when loading packages to ensure proper configuration and prevent deployment issues. The platform performs four main types of validation: name validation to ensure the package name matches the directory and filename exactly (case-sensitive) and contains only valid characters, version validation to confirm the version follows semantic versioning format with only numbers and dots, dependency validation to verify that all dependency packages exist and version constraints can be satisfied without circular dependencies, and JSON syntax validation to ensure the manifest is well-formed JSON with proper quotation marks and comma placement.
Name validation examples:
Valid: Directory myApp/, manifest myApp/myApp.c3pkg.json, name field "myApp" all match exactly.
Invalid: Directory MyApp/ but name field "myApp" results in Package name must match directory name.
Version validation examples:
Valid formats: "1.0" (Major.Minor), "1.0.0" (Major.Minor.Patch), "2.5.3".
Invalid formats: "1" (too short), "v1.0" (includes prefix), "1.0.0-beta" (prerelease tag not supported).
Dependency validation examples:
Error when package not found: Dependency package 'unknownPackage' not found.
Error when versions incompatible: Cannot resolve version constraint for 'platform': requires 8.4.0, available 8.3.0.
Error when circular dependency: Circular dependency detected: packageA -> packageB -> packageA.
How dependencies affect your package
What Types are available
Dependencies determine which Types your package can use. The C3 Agentic AI Platform uses breadth-first search (BFS) to discover all Types available to your package - it starts with your direct dependencies, then their dependencies, and so on. This means Types from transitive dependencies (dependencies of your dependencies) are automatically available to you.
The platform uses depth-first search (DFS) to detect circular dependencies where packages depend on each other in a cycle, which would make it impossible to determine load order. The compatibleToVersion field enables flexible version resolution - if foundation:1.5.0 declares compatibleToVersion: "1.2", then any package requiring foundation:1.2 or later can use version 1.5.0. Resolved versions are cached in /gen/cache/resolvedVersions.json.
When seed data redeploys unexpectedly
Your seed data files might reference Types from dependency packages. When you change dependencies in the manifest (adding, removing, or updating versions), the Types available to your package change. A Type that existed in version 1.0 of a dependency might be modified or removed in version 2.0, which could make your existing seed data invalid or reference non-existent Types. To ensure data consistency, the C3 Agentic AI Platform must redeploy seed data whenever dependencies change.
The platform tracks package changes using fingerprints - a hash computed from all files and metadata in your package. Any change to the manifest (including the name, version, or dependencies fields) creates a new package fingerprint. When the platform detects a fingerprint change, it automatically redeploys seed data for that package using DbLock to prevent concurrent deployment. This is why adding a new dependency or incrementing your version causes seed data to reload in all environments, even though you didn't modify any seed files directly.
Understanding this behavior helps you control when redeployment happens. For example, you can plan dependency updates during maintenance windows to avoid unexpected seed data reloading in production environments where consistency matters most.
See also
- Package structure overview - Complete package organization.
- Source folder structure - Organizing Type definitions and implementations.