As an experienced website operation expert, I know that structured data (Schema Markup), especially Json-LD, plays a core role in current search engine optimization.AnQiCMS (AnQiCMS) provides users with powerful and flexible content management capabilities while also fully considering SEO requirements, incorporating a rich set of SEO tools, including support for Json-LD.

In Anqi CMS, the system defaults to generating some Json-LD structured data on the page based on the content type.But for many operators who hope to fine-tune the display of content and improve the depth of search engine understanding, customizing Json-LD is an unavoidable requirement.{% jsonLd %}...{% endjsonLd %}Such template tags, Anqi CMS provides great freedom.However, this freedom is also accompanied by strict requirements for JSON syntax.Once JSON syntax errors occur, not only will custom structured data fail to take effect, but it may also affect the presentation of structured data throughout the entire page, thus missing the SEO opportunity.

Today, let's delve deeply into how to avoid common JSON syntax 'traps' when customizing Json-LD in AnQi CMS.

In AnQi CMS, customize the 'entry' and 'rules' of Json-LD

In the template system of AnQi CMS, we use{% jsonLd %}A tag to embed custom Json-LD code blocks.The beauty of this tag lies in its ability to allow you to write JSON code that conforms to the Json-LD standard.It is even smarter that AnQiCMS automatically merges the Json-LD you customize with the default Json-LD generated by the system.This means you can easily supplement or override some of the fields provided by the system by default to achieve personalized display.

However, the foundation of this merge is that the JSON code you provided must becorrect in format and grammarperiod.If there are any JSON syntax errors in your custom code, AnQiCMS will encounter obstacles during parsing, resulting in your intentions not being correctly conveyed to the search engine.Therefore, it is crucial to understand and avoid common JSON syntax errors.

common 'traps' in JSON syntax and ways to avoid them

When we talk about JSON syntax, it is much more strict than one might imagine, and any little oversight can lead to parsing failure. The following are some of the most commonly encountered 'traps' when customizing Json-LD:

  1. The strict requirement of double quotes: key names and string values must be enclosed in double quotesThe JSON syntax is very strict about the use of quotes. All field names (field name) and all string values (string value) must useQuotation marks"wrap it.This is one of the most common and easiest mistakes, many people are accustomed to the usage of unquoted key names or single quotes in JavaScript object literals, which are not allowed in JSON.

    • Incorrect example: 
      
{
    author: "AnQiCMS",
    'image': "https://en.anqicms.com/anqicms.png"
}
    • Correct format: 
      
{
    "author": "AnQiCMS",
    "image": "https://en.anqicms.com/anqicms.png"
}

  2. The art of commas: just right, not too much, not too littleIn JSON, each key-value pair and each element of the array must be separated bycomma,. However, a very subtle and easily overlooked mistake is,The last key-value pair or the last array element must not have an trailing commaAlthough some programming languages or environments allow trailing commas for convenience in code management, the JSON standard strictly prohibits them.

    • Incorrect example (trailing comma): 
      
{
    "author": "AnQiCMS",
    "image": "https://en.anqicms.com/anqicms.png", // 多余的拖尾逗号
}
    • Incorrect example (missing comma): 
      
{
    "author": "AnQiCMS"
    "image": "https://en.anqicms.com/anqicms.png" // 缺少逗号
}
    • Correct format: 
      
{
    "author": "AnQiCMS",
    "image": "https://en.anqicms.com/anqicms.png"
}

  3. The aesthetic of parentheses: structurally complete, with a beginning and an endThe data structure of JSON is defined by curly braces{}Define an object (object), defined by square brackets[]Define an array (array).These brackets must be strictly paired and correctly nested.A JSON object or array that lacks closing brackets will result in a structural error in the entire JSON code.When the content of Json-LD becomes complex, it is particularly important to be careful with the nested brackets.

    • Incorrect example: 
      
{
    "author": "AnQiCMS",
    "image": [
        "https://en.anqicms.com/anqicms.png"
    // 缺少了方括号的闭合 `]`
} // 缺少了花括号的闭合 `}`
    • Correct format: 
      
{
    "author": "AnQiCMS",
    "image": [
        "https://en.anqicms.com/anqicms.png"
    ]
}

  4. The magic of escaping special characters: the 'mystery' within the stringIf your string value itself contains double quotes"、backslash\and other special characters, they must beescapedA backslash is added in front of it\Otherwise, the parser will misinterpret the string as ending here, resulting in a syntax error. For example, if you want to include a double quote in the string, you need to write it as\".

    • Incorrect example: 
      
{
    "description": "这是一段包含"双引号"的描述"
}
    • Correct format: 
      
{
    "description": "这是一段包含\"双引号\"的描述"
}

  5. The precise match of data types: conforms to JSON standardsExcept for the above points, JSON also has strict definitions of data types: strings (string), numbers (number), booleans (boolean:true/falseEmpty valuenullObject and array. Although at the Json-LD level, certain fields (such asratingValue) There will be flexible handling of numbers or strings, but at the pure JSON syntax level, undefined types are not allowed, such as using variable names directly at the value position (not in string form), or using JavaScript'sundefined.

    • Incorrect example: 
      
{
    "reviewCount": undefined, // JSON不支持undefined
    "ratingValue": "5.0"      // 如果schema要求是数值类型，但这里是字符串
}
    • Correct format: 
      
{
    "reviewCount": null,      // 如果没有值，应使用null
    "ratingValue": 5.0        // 如果schema要求是数值
}

Diagnosis and debugging: A powerful 'tool' that saves effort

It is important to avoid errors, but it is also crucial to quickly locate and fix them when they occur. Fortunately, we have some very practical tools to help you:

  • Google Structured Data Testing Tool / Schema Markup Validator:This is the most commonly used tool for Json-LD developers.You can directly paste the Json-LD code into it, it will not only check if the JSON syntax is correct, but will also verify whether your Json-LD structure is valid according to the Schema.org specification, whether there are any warnings or errors.It is strongly recommended to use this tool to validate the code before deploying it to the Anqi CMS template.
  • Online JSON validator (such as JSONLint):This is a pure JSON syntax verification tool, which can quickly judge whether the code you provide is a valid JSON format and point out the specific syntax error position.
  • Code Editor:Modern code editors (such as VS Code, Sublime Text) typically have built-in features for automatic highlighting and error checking of JSON syntax.When you are editing Json-LD code, they can point out syntax errors in real time, helping you to find problems before saving.

Practical suggestions in Anqi CMS

When you use template files in Anqi CMS{% jsonLd %}Please follow the following suggestions when customizing Json-LD tags:

  1. Start from the small, add gradually:Do not write a large amount of complex Json-LD code at once. Start with the simplest structure, gradually add fields and nesting, and test each part as you add it.