Manifest reference

This page is the reference for the extension.json manifest used by manifest-shipping extensions, including curated packages and graduated standalone packages.

The lfx-bundles metapackage uses manifest-less discovery through the lfx.bundles group and does not use extension.json.

The canonical JSON Schema lives at https://schemas.langflow.org/extension/v1.json and is generated from the Pydantic model at lfx.extension.manifest.ExtensionManifest.

To export the live schema, run:

lfx extension schema --output extension.schema.json

Use the $schema reference in your manifest so editors can autocomplete and validate inline:

{
  "$schema": "https://schemas.langflow.org/extension/v1.json",
  "id": "lfx-my-extension",
  "version": "0.1.0",
  "name": "My extension",
  "lfx": { "compat": ["1"] },
  "bundles": [{ "name": "my_bundle", "path": "components/my_bundle" }]
}

Top-level fields

additionalProperties: false — any field not listed here is rejected with a typed error. Reserved names (services, routes, hooks, starterProjects, userConfig) are documented under Deferred fields and surface a more specific error code.

An extension must declare at least one entry in either bundles or providers. It can declare both when one package contributes components and model providers.

lfx: compatibility declaration

"lfx": { "compat": ["1"] }

The runtime compares str(BUNDLE_API_VERSION) against this list. A mismatch fails install with version-constraint-unsatisfied. v0 accepts only "1"; lists like ["1", "2"] become meaningful when a future BUNDLE_API revision ships.

bundles

"bundles": [
  { "name": "my_bundle", "path": "components/my_bundle" }
]

v0 enforces maxItems: 1; multi-bundle extensions are rejected with multi-bundle-unsupported and ship in a later epic. The list can be empty when the extension declares at least one model provider.

providers

A provider-only extension can add a provider without adding a component bundle:

{
  "$schema": "https://schemas.langflow.org/extension/v1.json",
  "id": "lfx-acme-models",
  "version": "0.1.0",
  "name": "Acme Models",
  "lfx": { "compat": ["1"] },
  "providers": [
    {
      "name": "Acme",
      "provider_id": "acme.models",
      "display_name": "Acme Models",
      "aliases": ["Acme Legacy"],
      "metadata": {
        "icon": "Bot",
        "variables": [],
        "mapping": {
          "model_class": "ChatAcme",
          "model_param": "model"
        }
      },
      "api_key_required": false,
      "model_class": {
        "module": "langchain_acme",
        "attr": "ChatAcme",
        "install_hint": "langchain-acme"
      },
      "catalog_loader": "lfx_acme.catalog:load_models"
    }
  ]
}

catalog_loader must return a flat list[dict]. Every row requires a non-empty name; model_type can be llm or embeddings and defaults to llm. Langflow overwrites any supplied provider value with the descriptor's canonical name, supplies the provider icon when omitted, and rejects duplicate (model_type, name) identities. Deployments that require an extension catalog can call validate_registered_provider_catalogs() or get_registry_snapshot(validate_catalogs=True) during readiness.

Providers that use ambient authentication or need no credentials should set api_key_required to false. They remain eligible for unified model options when metadata.variables is empty or contains only optional configuration fields.

Built-in providers take precedence over extension declarations. A provider-name collision is skipped without preventing other providers or components from loading. Stable-ID or alias collisions are reported as provider-invalid.

capabilities

Optional. Defaults to { "requiresCredentials": false }.

Additional capability keys are rejected with extra="forbid" so a misspelled key surfaces immediately rather than silently turning a feature off.

Deferred fields

The schema strips these names from the published properties map but reserves them via x-deferred-fields, so a manifest that sets one gets a specific error code instead of the generic "additional property" message.

A manifest that sets any of these to a non-null value is rejected at validate / load time. Setting them to null is allowed (the loader treats null and absent identically).

Pyproject alternative

If you'd rather not ship a separate extension.json next to pyproject.toml, declare the same fields under [tool.langflow.extension]:

[tool.langflow.extension]
id = "lfx-my-extension"
version = "0.1.0"
name = "My extension"

[tool.langflow.extension.lfx]
compat = ["1"]

[[tool.langflow.extension.bundles]]
name = "my_bundle"
path = "components/my_bundle"

The loader prefers an extension.json when both exist. The Pydantic validator is the same so error codes and field semantics are identical.

Error codes raised against this manifest

The loader and validator both emit typed errors keyed by the manifest field that triggered them. The full reference is on the Extension error codes page; the codes most relevant when authoring a manifest are:

Run lfx extension validate <path> to see every error as a structured object with code, message, location, hint, and ref_url.

See also

• Extensions overview
• Build your first extension
• About LFX
• Extension error codes