Skip to content

Configuration File Overview

The jellyspec.json file is the primary configuration file for defining functions in the JellyFaaS ecosystem. It outlines the following key details:

  • Deployment Settings: Function Name, entrypoint, runtime, etc.

  • Inputs: Request schema (query parameters and request body)

  • Outputs: Response schema (response body)

The configuration serves multiple purposes, helping to simplify development and ensure the correct usage of the function:

  • Documentation: It is used by the JellyFaaS website to guide other developers.

  • AI Integration: It enables JellyFaaS AI tools to interact with the function.

  • SDK Validation: It allows the SDK to validate outgoing requests.

Learn more

The jellyspec.json config file makes heavy use of the JSON format and JSON Schema standard to define functions. For more on these topics, see:

Getting started with a template

Here are some configuration file examples to help you get started.

An minimal template with only runtime/deployment configuration. This corresponds to a Python 3.12 function with no inputs or outputs.

{
    "name": "Do Nothing Machine",
    "shortname": "do_nothing",
    "description": "Does nothing",
    "runtime": "python312",
    "entrypoint": "Main",
    "requirements": {
        "requestType": "GET",
        "queryParams":[],
        "inputType": "NONE",
        "outputType": "NONE"
    },
    "tags":[
        "template"
    ]
}

A simple "greeter" function which takes a name query parameter and returns a JSON response containing the concatenated greeting: {"greeting":"Hello, foo!"}.

name is included as a required query parameter.

Because outputType is set to "JSON", outputSchema must be included and is interpreted as a JSON Schema.

Note

Notice inputType is still set to "NONE", despite the function using a query parameter, name. This is because input (and corresponding output) properties relate to the body of an HTTP request/response, which does not include query params.

In short, queryParams has no effect on inputType, inputSchema, outputType, or outputSchema properties.

{
    "name": "Simple Greeter",
    "shortname": "simple-greeter",
    "description": "Takes a name as a query param and greets you!",
    "runtime": "go122",
    "entrypoint": "Main",
    "requirements": {
        "requestType": "GET",
        "queryParams": [
            {
                "name": "name",
                "required": true,
                "description": "Name of person to greet",
                "exampleData": "name=foo"
            }
        ],
        "inputType": "NONE",
        "outputType": "JSON",
        "outputSchema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "Greeting Schema", 
            "description": "Describes a JSON object of the form {\"greeting\":\"some string\"}.",
            "type": "object",
            "properties": {
                "greeting": {
                    "type": "string",
                    "description": "The full greeting, \"Hello, <name>!\""
                }
            },
        },
        "outputDescription": "Greeting",
        "outputJsonExample": "{\"greeting\":\"hello, foo!\"}"
    },
    "tags": [
        "template"
    ]
}

A function which accepts an image file and watermark text (e.g. the photographer's name), then returns a watermarked image.

Because inputType is set to "JSON", inputSchema must be included and is interpreted as a file schema.

outputType and outputSchema is handled the same, with the exception that the required field is not applicable in response schemas, so it is omitted.

Note

Since inputType is not "NONE", requestType cannot be set to "GET", as HTTP protocol does not allow GET requests to include request bodies. Therefore, we use "POST" instead.

{
    "name": "Watermark Image Function",
    "shortname": "watermarker",
    "description": "Takes an image and watermark text, returns watermarked image",
    "runtime": "python312",
    "entrypoint": "Main",
    "requirements": {
        "requestType": "POST",
        "queryParams": [
            {
                "name": "text",
                "required": true,
                "description": "The text to apply to the image",
                "exampleData": "text=john_smith_photography"
            }
        ],
        "inputType": "FILE",
        "inputSchema": {
            "description": "The input image file",
            "extensions": ["png", "jpg", "jpeg"],
            "required": true,
        },
        "outputType": "FILE",
        "outputSchema": {
            "description": "The output (watermarked) image file",
            "extensions": ["png", "jpg", "jpeg"]
        }
    },
    "tags": [
        "template"
    ]
}

Reference

$jellyspecversion string

Specifies the version of this configuration file format. The only valid value is "v1.0.0".

name string

The human-readable name of the function. name may include spaces and special characters.

This property is purely for presentation/readability, while shortname is used to reference the function via code.

shortname string

The function ID. This is used to generate the function's endpoint, and is used to reference the function via code. shortname may not include special characters, except for hyphens and underscores.

Warning

You will need to provide a unique shortname, you can check if a using the following CLI command jellyfaas exists -n to see if the name is already taken, or search via the app.

runtime string

The language and version the function is coded in. This is used internally to deploy the function correctly. The supported runtimes for each language include:

Node.js Python Go Java Ruby PHP .NET
nodejs20 python312 go122 java21 ruby32 php82 dotnet8
nodejs18 python311 go121 java17 ruby30 php81 dotnet6
nodejs16 python310 go120 java11 ruby27 php74
nodejs14 python39 go119 ruby26
nodejs12 python38 go118
nodejs10 python37 go116
nodejs8 go113
nodejs6 go112
go111

Note

The language the function is written in (and therefore the runtime property) have no effect on the language(s) used to invoke the function. All functions, regardless of runtime, may be invoked by REST and any JellyFaaS SDKs.

entrypoint string

The name of the entrypoint method, in the function's code. Case-sensitive.

For example, given a simple python cloud function: 

# main.py
import functions_framework
import json

@functions_framework.http
def App(request):
    return json.dumps({'data': 'Hello World!'}), 200
entrypoint would be set to "App".

description string

A short description of the function - ideally 1-2 sentences. This is used to populate some fields in the JellyFaaS website, and may help the function integrate with AI tools.

requirements object

The requirements property defines the function's inputs and outputs. It is composed of the following child properties:

requirements.requestType string

The HTTP method handled by the function.

Options:

  • "GET"
  • "POST"
  • "PUT"
  • "DELETE"

Note

HTTP protocol does not allow GET requests to include request bodies. This is fine with inputType set to "NONE".

Otherwise, be sure to use requestType set to "POST", "PUT", or "DELETE".

requirements.inputType string

The expected format of the request body. May be omitted to default to "NONE"

Options:

  • "NONE" (default)

    If the function does not expect a request body, inputType should be set to "NONE" and inputSchema should be omitted.

  • "JSON"

    If the function expects a JSON format request body, inputType should be set to "JSON" and inputSchema will be interpreted as JSON Schema. Additionally, inputJsonExample may also be included as a example, otherwise it should be omitted.

  • "FILE"

    If the function expects a file request body, inputType should be set to "FILE" and inputSchema will be interpreted as file schema.

requirements.outputType string

The format of the response body. May be omitted to default to "NONE"

Options:

  • "NONE" (default)

    If the function does not return a response body, outputType should be set to "NONE" and outputSchema should be omitted.

  • "JSON"

    If the function returns a JSON format response body, outputType should be set to "JSON" and outputSchema will be interpreted as JSON Schema. Additionally, inputJsonExample may also be included as a example, otherwise it should be omitted.

  • "FILE"

    If the function returns a file response body, outputType should be set to "FILE" and outputSchema will be interpreted as file schema.

requirements.queryParams array

A list of query parameters expected by the function. Here is an example queryParams: 

"queryParams": [
    {
        "name": "width",
        "required": true,
        "description": "Width to resize some input image to",
        "exampleData": "width=640"
    },
    {
        "name": "height",
        "required": true,
        "description": "Height to resize some input image to",
        "exampleData": "height=360"
    }
],

Each item of queryParams should be an object with the following properties:

name string

The name or "key" of the query parameter. Should be lowercase, with no special characters.

required boolean

Default value: false

If the function requires this parameter to be specified, required should be true. If the parameter is optional, choose false.

description string

A short description of the usage of the query parameter. This is used to populate the website and aides with integration with AI tools.

exampleData string

A snippet showing correct usage of the query param, ideally in <name>=<value> format. e.g. "exampleData":"town=bath"

requirements.inputSchema object

inputSchema defines the expected structured of incoming HTTP request bodies. It is used by the JellyFaaS website for documentation on the function's page, by the SDKs to validate outgoing client requests, and for AI function calling.

inputSchema is interpreted differently, depending on the value of inputType.

  • If inputType is "NONE" (or omitted), then inputSchema should be omitted.
  • If inputType is "JSON", then inputSchema is interpreted as a JSON Schema object.
  • If inputType is "FILE", then inputSchema is interpreted as a file schema object.
requirements.inputSchema (as JSON Schema) object

Schema of incoming JSON bodies. i.e., requests with Content-Type: application/json.

Must conform to the JSON Schema specification. For details, see JSON Schema documentation.

JSON Schema Limitations

Be aware that some advanced features of JSON Schema may not work fully with AI function calling or SDK request validation.

For guidance on which features are supported, refer to OpenAI's Supported Schemas documentation.

As an example, given a function which expects the following nested JSON object:

{
    "employee": {  
        "name": "sonoo",   
        "salary": 56000,   
        "married": true
    }  
}

A JSON Schema could be created to describe this structure: 

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "employee": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "salary": {
                    "type": "integer"
                },
                "married": {
                    "type": "boolean"
                }
            },
            "required": [
                "name",
                "salary",
                "married"
            ]
        }
    },
    "required": [
        "employee"
    ]
}

CLI Generation

The JellyFaaS CLI can help convert JSON to JSON Schema. See CLI Commands for more.

requirements.inputSchema (as File Schema) object

A description of a single file input expected by the function. Here is an example inputSchema describing a file of various expected image formats: 

"inputSchema": {
    "description": "The input image file",
    "extensions": ["png", "jpg", "jpeg"],
    "required": true,
}

inputSchema has the following properties:

description string

A short description of the usage of the file. This is used to populate the website for documentation.

extensions string

A list of valid, accepted file extensions. This is used by the SDK to validate requests.

required boolean

Default value: false

If the function requires this parameter to be specified, required should be true. If the parameter is optional, choose false.

requirements.inputJsonExample string

A short example of a valid JSON input. Should be omitted if inputType is not JSON.

requirements.outputSchema object

inputSchema vs outputSchema

outputSchema follows the same general structure as inputSchema. The main difference is the omission of required properties.

outputSchema defines the structured of outgoing HTTP response bodies. It is used by the JellyFaaS website for documentation on the function's page, by the SDKs to validate incoming responses, and for AI function calling.

outputSchema is interpreted differently, depending on the value of outputType.

  • If outputType is "NONE" (or omitted), then outputSchema should be omitted.
  • If outputType is "JSON", then outputSchema is interpreted as a JSON Schema object.
  • If outputType is "FILE", then outputSchema is interpreted as a file schema object.
requirements.outputSchema (as JSON Schema) object

Schema of outgoing JSON bodies. i.e., responses with Content-Type: application/json.

Must conform to the JSON Schema specification. For details, see JSON Schema documentation.

JSON Schema Limitations

Be aware that some advanced features of JSON Schema may not work fully with AI function calling or SDK request validation.

For guidance on which features are supported, refer to OpenAI's Supported Schemas documentation.

As an example, given a function which returns the following nested JSON object:

{
    "employee": {  
        "name": "sonoo",   
        "salary": 56000,   
        "married": true
    }  
}

A JSON Schema could be created to describe this structure: 

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "employee": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "salary": {
                    "type": "integer"
                },
                "married": {
                    "type": "boolean"
                }
            },
            "required": []
        }
    },
    "required": []
}

CLI Generation

The JellyFaaS CLI can help convert JSON to JSON Schema. See CLI Commands for more.

requirements.outputSchema (as File Schema) object

A description of a single file returned by the function. Here is an example outputSchema describing a file of various expected image formats: 

"outputSchema": {
    "description": "The output image file",
    "extensions": ["png", "jpg"]
}

outputSchema has the following properties:

description string

A short description of the usage of the file. This is used to populate the website for documentation.

extensions string

A list of returned file extensions. This is used to populate the website for documentation.

requirements.outputJsonExample string

A short example of a valid JSON output. Should be omitted if outputType is not JSON.

tags array

A list of tags for use with the JellyFaaS website. This aides in searchability. Tags should be lowercase, with no special characters.