hasura/graphql-engine · error · OpenDdDeserializeError

{error} at path {path}

Error message

{error} at path {path}

What it means

OpenDd deserialize error from the open-dds crate: converting a JSON value into an OpenDd type failed at a specific JSON path. The serde_json error says what failed to parse; the path tells you where in the document it happened.

Source

Thrown at v3/crates/open-dds/src/traits.rs:249

                // Only generate an $id if an $id is not already present and if a title has been set.
                // Downstream tooling doesn't handle $id without a title well and if a schema doesn't have a title,
                // then it likely isn't significant enough to warrant an $id.
                if metadata.id.is_none() && metadata.title.is_some() {
                    metadata.id = Some(format!(
                        "https://hasura.io/jsonschemas/metadata/{schema_name}"
                    ));
                }
            }
        }
    }

    deduplicate_definitions(&mut root_schema);
    root_schema
}

/// Error type for deserializing OpenDd types from JSON values.
#[derive(Debug, thiserror::Error)]
#[error("{error} at path {path}")]
pub struct OpenDdDeserializeError {
    #[source]
    pub error: serde_json::Error,
    pub path: jsonpath::JSONPath,
}

#[cfg(test)]
mod tests {
    use crate::traits;
    use opendds_derive::OpenDd;
    use pretty_assertions::assert_eq;
    use serde_json;

    #[test]
    fn test_parse_versioned_enum() {
        #[derive(Debug, PartialEq, OpenDd)]
        struct MyStruct {
            name: String,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Look at the reported path and fix the value at that exact location in the JSON/hml file
2. Regenerate metadata with the CLI version matching your project instead of hand-editing
3. Upgrade/downgrade the open-dds crate to match the metadata schema version you are consuming

Example fix

// before
{ "kind": "Model", "name": 123 }
// after
{ "kind": "Model", "name": "user" }

// Validate against the expected shape with a JSON Schema before deserializing
jsonschema::validate(&schema, &json_value)?;

match open_dd::traits::OpenDdSubTypes::from_json_value(value) {
    Err(e @ OpenDdDeserializeError { .. }) => {
        eprintln!("{} at {}", e.error, e.path); // fix the document at e.path
    }
    Ok(v) => v,
}

When it happens

Trigger: Calling OpenDd deserialization helpers (e.g. open_dd_root_from_json / the traits in open-dds/src/traits.rs) on a JSON document where the value at `path` does not match the expected schema — wrong field type, unknown/missing required key, malformed structure.

Common situations: Hand-editing .hml/json metadata and introducing a typo or wrong value type (string where number expected); feeding a CI-exported JSON produced by an older/newer CLI version whose schema changed; forgetting to regenerate metadata after a breaking change.

Related errors

• failed parsing json: %w; response from API: %s
• reading metadata file: %w
• Unknown type: {type_name}
• The field {field_name:} has type {field_type:} but the field
• multiple graphql types found with the same name: {graphql_ty

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/4bfa3c8832e9e315. Report an issue: GitHub.