{"record":{"id":"815d7651850930ed","repo":"siyuan-note/siyuan","slug":"createdoctree-document-contains-unknown-field-s","errorCode":null,"errorMessage":"createDocTree document contains unknown field [%s]","messagePattern":"createDocTree document contains unknown field \\[(.+?)\\]","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/template_doc_tree.go","lineNumber":143,"sourceCode":"\tvalues, ok := value.([]any)\n\tif !ok {\n\t\treturn nil, errors.New(\"createDocTree definition must be a list\")\n\t}\n\tif 0 == len(values) {\n\t\treturn nil, errors.New(\"createDocTree document list must not be empty\")\n\t}\n\n\tnodes := make([]*TemplateDocTreeNode, 0, len(values))\n\tfor _, value := range values {\n\t\tdefinition, ok := value.(map[string]any)\n\t\tif !ok {\n\t\t\treturn nil, errors.New(\"createDocTree document must be a dictionary\")\n\t\t}\n\t\tfor key := range definition {\n\t\t\tswitch key {\n\t\t\tcase \"title\", \"template\", \"define\", \"children\":\n\t\t\tdefault:\n\t\t\t\treturn nil, fmt.Errorf(\"createDocTree document contains unknown field [%s]\", key)\n\t\t\t}\n\t\t}\n\n\t\ttitleValue, ok := definition[\"title\"]\n\t\tif !ok {\n\t\t\treturn nil, errors.New(\"createDocTree document title is required\")\n\t\t}\n\t\ttitle, ok := titleValue.(string)\n\t\tif !ok {\n\t\t\treturn nil, errors.New(\"createDocTree document title must be a string\")\n\t\t}\n\t\ttitle = normalizeDocTitle(title)\n\t\tif \"\" == title {\n\t\t\treturn nil, errors.New(\"createDocTree document title must not be empty\")\n\t\t}\n\t\tif 512 < utf8.RuneCountInString(title) {\n\t\t\treturn nil, fmt.Errorf(\"createDocTree document title exceeds %d characters\", 512)\n\t\t}","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/8641553a1f07374001902d3ce773285db1292b2d/kernel/model/template_doc_tree.go#L125-L161","documentation":"createDocTree document objects allow only four fields: title, template, define, children. Any other key (including misspellings like tittle or extraneous metadata such as id or icon) causes the parser to fail with the offending key name. This strict allowlist catches typos that would otherwise be silently ignored.","triggerScenarios":"A document object containing any key other than title/template/define/children, e.g. {\"tittle\": \"X\"}, {\"title\": \"X\", \"note\": \"...\"}, or copied IAL attributes like custom-* keys pasted into the definition.","commonSituations":"Typos in field names (titel, chidren); carrying over fields from other SiYuan template syntaxes; LLM-generated templates inventing plausible-sounding fields; merging document IAL metadata into the tree definition.","solutions":["Read the offending key from the error message and remove or rename it to one of title, template, define, children.","Fix common misspellings: children (not childs/chidren), title (not tittle/titel).","Move intended metadata (aliases, custom-*) into the rendered template content instead of the tree definition.","Validate the definition against the four-field schema before rendering to catch this in tooling rather than at runtime."],"exampleFix":"// before\n{\"title\": \"Doc\", \"tittle\": \"Doc\", \"custom-flag\": \"1\"}\n// after\n{\"title\": \"Doc\"}","handlingStrategy":"validation","validationCode":"allowed := map[string]bool{\"title\": true, \"template\": true, \"define\": true, \"children\": true}\nvar walk func(nodes []any) error\nwalk = func(nodes []any) error {\n    for _, v := range nodes {\n        m, ok := v.(map[string]any)\n        if !ok { continue }\n        for k := range m {\n            if !allowed[k] {\n                return fmt.Errorf(\"unknown field [%s]\", k)\n            }\n        }\n        if c, ok := m[\"children\"]; ok {\n            if cl, ok := c.([]any); ok {\n                if err := walk(cl); err != nil { return err }\n            }\n        }\n    }\n    return nil\n}","typeGuard":"var docFields = map[string]bool{\"title\": true, \"template\": true, \"define\": true, \"children\": true}\nfunc hasOnlyKnownFields(m map[string]any) bool {\n    for k := range m {\n        if !docFields[k] { return false }\n    }\n    return true\n}","tryCatchPattern":"nodes, err := parseTemplateDocTreeDefinition(def)\nif err != nil {\n    if strings.Contains(err.Error(), \"unknown field\") {\n        // strip or rename the offending key reported in [%s] and retry\n    }\n    return err\n}","preventionTips":["Remember the exact allowlist: title, template, define, children — nothing else.","Spell-check field names when hand-editing templates (children, not childs).","Keep document metadata like custom-* attributes in template content, not in the tree definition."],"tags":["template","schema","unknown-field"],"backgroundTag":"schema-validation-failed","analyzedSha":"8641553a1f07374001902d3ce773285db1292b2d","analyzedAt":"2026-09-11T16:08:28.414Z","contentChangedAt":"2026-09-11T16:08:28.414Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}