---
title: "记录你的数据模型/架构的五个主要原因"
date: "2016-06-29"
categories: 
  - "development"
  - "json"
  - "xbrl"
  - "xml"
tags: 
  - "schema-documentation"
  - "xml-editor"
  - "xmlspy"
  - "xsd"
description: 探索 XML 和 JSON 开发中模式文档的重要性。了解它如何提升团队沟通、项目整合以及利益相关者之间的协作。
---
Status: #blog

Tags:  #schema-documentation #xml-editor #xmlspy #xsd

Categories: [development](/blog/zh/category/development.md) | [json](/blog/zh/category/json.md) | [xbrl](/blog/zh/category/xbrl.md) | [xml](/blog/zh/category/xml.md)
# 记录你的数据模型/架构的五个主要原因

模式（Schema）的开发通常是一个迭代过程，开发者通常不会从零开始——XML 模式以及，越来越多地，JSON 模式，通常是由现有文档拼接而成，或者从其他团队继承而来。 能够理解模式组件之间的关系，并分析关于开发选择的说明，对于提高效率至关重要，但由于缺乏有效的文档，这往往难以实现。

让我们来看看一些原因，说明为什么文档应该成为您在开发XSD、JSON或其他模式文件时不可或缺的一部分。

##  ![XSD文档的优势](/blog/images/xsd_documentation_blog.jpg)

<!--more-->

### XSD 模式文档的优势

以下是您在为下一个数据模型进行设计时，不应该跳过文档编写步骤的几个主要原因。

1. **它能够促进开发团队成员之间的便捷沟通。**

模式开发通常是一个协作过程，清晰、简洁的文档有助于避免混淆，并提高生产力，因为不同的开发人员会处理模式或一系列模式的不同方面。 此外，清晰的文档也有助于进行同行评审，让多位专家可以对内容模型进行评估和反馈。

2. **可以快速地理解和掌握已有的项目。**

这与上一条观点密切相关。无论是从被收购的公司获得的代码，还是从其他部门转过来的代码，都应该有完善的文档。即使项目最初是在您的组织内部开发的，但最初的开发者可能已经离职，或者开发工作可能被分摊给不同的个人，导致没有人能够完全了解整个项目。

当然，很少有项目仅仅由模式（schemas）构成。为了对现有代码进行全面的分析，建议 [生成 UML 图](https://www.altova.com/zh/umodel.html) 用于记录项目信息，并方便地进行可视化展示。

3. **集中管理有关导入或包含的模式（schema）的信息。**

与其费力地逐一查阅大量文档以确定其中的关联关系，模式文档可以将所有相关文档的信息集中在一个地方进行呈现。

4. ** 允许非技术人员理解和分析模式定义**

由于模式文档是人类可读的，这为与广泛的领域专家进行合作提供了可能，他们可以在模式的开发和演进过程中理解并提供意见。

5. **自动化工具让操作变得简单。**

实际上，在软件简化了这一过程的情况下，没有理由不记录你的数据结构。让我们来看看如何使用一款工具——XMLSpy——来完成这项工作。

 

XMLSpy 提供了完全可定制，但又功能全面的模式文档，适用于 XSD 模式、JSON 模式和 XBRL 分类模式。 让我们来看看它是如何工作的。

### 生成 XML 模式文档

![生成 XML 模式文档](/blog/images/generate-xsd-documentation.png "Generate XML Schema documentation")

 

[XMLSpy XML 编辑器](https://www.altova.com/zh/xmlspy.html) 能够自动生成 XML 模式、JSON 模式、XBRL 分类体系模式以及 [WSDL 定义](https://www.altova.com/zh/xmlspy/wsdl-editor.html) 的文档，并且生成过程对于每种类型都类似。打开相应的模式文档后，在“模式设计”菜单中选择“生成文档”。

您可以选择使用内置的文档模板，或者，如果您已安装 [Altova StyleVision](https://www.altova.com/zh/stylevision.html)，您可以根据自己的需求设计自定义模板。然后，选择以HTML、Word、RTF或PDF格式生成文档。（注意：PDF格式的生成需要确保StyleVision已安装在同一台计算机上。）

 

![XSD 文档选项](/blog/images/documentation-options.png)

 

其他选项允许您定义如何处理图像，并且最终，您可以精确地指定哪些组件和细节需要进行文档化。接下来，我们来看一下为XSD生成的文档，然后我将向您展示为JSON和XBRL模式生成文档的各种选项。

以下是 XMLSpy 示例项目中包含的“费用报告”XSD 的一部分 HTML 文档。

 

![HTML 中的模式文档](/blog/images/html-schema-doc.png)

 

模式组件以图形方式显示，并同时展示相应的源代码。超链接功能方便用户交叉引用相关元素、属性和类型的详细信息。

各项属性和特征都清晰地呈现，方便用户立即进行分析。

 

![模式详情 ](/blog/images/facets-properties.png)

 

当引用了来自其他模式的组件时，这些模式也会被记录在案。

###  生成 JSON Schema 文档

目前正在进行的推广应用是： [JSON 模式 (JSON Schema)](https://www.altova.com/zh/xmlspy/json-schema-editor.html) 对 JSON 数据流进行数据验证，也凸显了对这种类型的数据结构，以及相关规范的文档的重要性。

JSON Schema 的文档生成选项与 XSD 的类似，但自然地针对 JSON 进行了优化，提供了包括属性、数组、模式等详细信息的选项。

 

![生成 JSON Schema 文档](/blog/images/json-schema-documentation-2.png)

### XBRL 术语表文档

现在我们来谈谈XBRL分类法，这是目前最复杂的结构化数据方案之一。这里的文档不仅对分类法开发者有帮助，也对非技术背景的XBRL相关人员，例如会计师和其他财务领域的专业人士，同样具有重要价值。

 

![XBRL 术语表结构详情](/blog/images/xbrl-taxonomy-documentation.png)

 

该功能位于XBRL菜单中 [XBRL 术语表编辑器](https://www.altova.com/zh/xmlspy/xbrl-taxonomy_editor.html), “生成文档”命令提供了常见的选项，但这次这些选项是专门针对XBRL组件，例如标签和链接库。

 

无论您使用的是 XSD、JSON 还是 XBRL 模式，生成文档以可视化、理解和沟通模式的结构和关系有很多好处。而使用 XMLSpy，您可以在几秒钟内自动生成文档，这消除了完成这项工作的任何障碍。

如果您尚未成为我们的客户，您可以[免费试用 XMLSpy 30 天](https://www.altova.com/zh/download-trial.html)。