conductor-oss/conductor · error · UnsupportedSchemaException

{location}: unknown JSON Schema keyword '{key}' at {path}. A

Error message

{location}: unknown JSON Schema keyword '{key}' at {path}. Allowed keywords: {SUPPORTED}.

What it means

SchemaSubsetValidator.validate throws UnsupportedSchemaException when a schema contains a key that is neither in the SUPPORTED set nor in KNOWN_UNSUPPORTED — i.e. a typo or a custom/extension keyword. The runtime inline validator would ignore an unknown key (silent permissive validation), so this guard rejects loudly to surface the mistake.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/util/SchemaSubsetValidator.java:147

            if (SUPPORTED.contains(key)) continue;
            if (KNOWN_UNSUPPORTED.contains(key)) {
                throw new UnsupportedSchemaException(
                        location
                                + ": uses unsupported JSON Schema keyword '"
                                + key
                                + "' at "
                                + (path.isEmpty() ? "<root>" : path)
                                + ". The PAC runtime validator implements a Draft-07 subset; "
                                + "keywords like $ref/allOf/oneOf/format would silently pass at "
                                + "runtime, producing permissive validation. Restrict the schema "
                                + "to: "
                                + String.join(", ", SUPPORTED)
                                + ".");
            }
            // Unknown keyword — not in either set. Could be a typo, could be
            // a custom extension. Either way, ambiguous behaviour at runtime:
            // reject loudly.
            throw new UnsupportedSchemaException(
                    location
                            + ": unknown JSON Schema keyword '"
                            + key
                            + "' at "
                            + (path.isEmpty() ? "<root>" : path)
                            + ". Allowed keywords: "
                            + String.join(", ", SUPPORTED)
                            + ".");
        }

        // Recurse into nested schemas via ``properties`` and ``items``.
        Object props = schema.get("properties");
        if (props instanceof Map<?, ?> propsMap) {
            for (Map.Entry<?, ?> entry : propsMap.entrySet()) {
                Object subSchema = entry.getValue();
                if (subSchema instanceof Map<?, ?> subMap) {
                    validateInternal(
                            (Map<String, Object>) subMap,

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Compare the offending key against the SUPPORTED list in the error message — fix typos to match a supported keyword.
2. Remove vendor/extension (`x-*`) keys; they have no runtime effect anyway.
3. If you believe the keyword should be supported, add it to SUPPORTED in SchemaSubsetValidator AND implement it in JavaScriptBuilder.schemaValidatorScript (the two sets must stay in lockstep).

Example fix

// before
{"type": "object", "properites": {"x": {"type": "string"}}, "x-meta": 1}
// after
{"type": "object", "properties": {"x": {"type": "string"}}}

try {
    SchemaSubsetValidator.validate(schemaMap, "tool/my-tool");
} catch (UnsupportedSchemaException e) {
    // unknown keyword — surface so the author can fix the typo / drop the extension
    throw new IllegalArgumentException(e.getMessage(), e);
}

boolean usesOnlyKnownKeywords(Map<String,Object> schema) {
    try { SchemaSubsetValidator.validate(schema, "precheck"); return true; }
    catch (UnsupportedSchemaException e) { return false; }
}

try { SchemaSubsetValidator.validate(schema, location); }
catch (UnsupportedSchemaException e) { return badRequest(e.getMessage()); }

When it happens

Trigger: A schema with a misspelled keyword (`requireed`, `properites`), a vendor extension (`x-foo`), or a Draft-04/2019-09 keyword outside both sets. validate() iterates keys, finds one in neither set, and throws.

Common situations: Typo in a hand-written schema; copy-paste from an OpenAPI spec that uses `x-` extensions; mismatch between the Draft version the author had in mind and the supported subset.

Related errors

• {location}: uses unsupported JSON Schema keyword '{key}' at
• ${usx.message}
• null condition
• condition exceeds 1024 characters
• Output does not Confirm to the schema. errors: %s

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/d7457adc84827fe4. Report an issue: GitHub.