[DX] GAP-14: uipath.json functions format is undocumented — the error message is the only spec #1504

Summary

The expected format for function entries in uipath.json is a plain string "module.py:function_name". This is not documented anywhere — the only specification is the error message produced when the wrong format is used.

Root Cause

After seeing the uipath.json entryPoints format (which uses objects with filePath, type, etc.), a developer would reasonably attempt:

{
  "functions": {
    "check_vendor_risk": {
      "filePath": "invoice_tools/vendor.py",
      "description": "Checks vendor risk level"
    }
  }
}

uipath init rejects this with:

Invalid function specification: '{"filePath": "..."}' — expected 'path/to/file.py:function_name'

The error message is the only documentation for the expected format. It is not mentioned in:

• CLI --help output
• The $schema file
• The getting-started guide
• Any samples

Workaround

Use the string format:

{
  "functions": {
    "check_vendor_risk": "invoice_tools/vendor.py:check_vendor_risk"
  }
}

Suggested Fix

1. Document the expected format in the $schema for uipath.json
2. Add it to the CLI --help output for uipath init
3. Add it to the getting-started guide and function samples
4. Consider accepting an object format for richer metadata:

   {
     "check_vendor_risk": {
       "filePath": "invoice_tools/vendor.py",
       "functionName": "check_vendor_risk",
       "description": "Checks vendor risk level in Salesforce"
     }
   }

   The CLI already generates descriptions in entry-points.json from docstrings — this would allow developers to provide them explicitly.

Impact

• Severity: Medium (documentation gap causing confusing errors)
• The error message is the only specification, which is a poor developer experience
• The object format is a reasonable assumption given the rest of uipath.json uses objects