MD-Models

Markdown models are a way to define data models in a human-readable format. The models can be used to generate code, documentation and other formats from a single source of truth.

Features

• Human-readable - Markdown models are easy to read and write for humans.
• Extendable - Extension is simple, diffable and mergable with other models.
• Machine-readable - Convert your model into other schema languages such as JSON Schema, XSD and more.
• Code generation - Generate code in different programming languages such as Python and Typescript.
• Documentation - Generate documentation pages for mkdocs.
• Validation - Validate data against the defined schema.
• Semantic - Define semantic relationships between data structures.

Motivation

There exist many ways to formalize real-world structures into data schemes and make them machine-readable and thus applicable in software solutions. However, existing schema languages such JSON Schema or XML Schema are often hard to read and write for humans, especially for non-developers. Markdown models aim to provide a human-readable way to define data models and invite users from different backgrounds to contribute to the definition of data models.

Wait, not another schema language!

We are aware that there are many schema languages out there, and we do not aim to replace them. Instead, we aim to provide a way to define data models in a human-readable format that can be used to convert into other schema languages and programming languages. Our goal is to provide a gateway for non-developers to contribute to the definition of data models and to make the process of defining data models more accessible to a broader audience, while ensuring the integrity into existing solutions.

How it works

Markdown models are defined in a simple markdown format. The format is based on the CommonMark specification and can be extended with custom syntax. The concept is simple: Level 3 headings initialize a new type and the following list items define the fields of the type.

Person.mdPerson.jsonPerson.xsd

### Person

This is a simple data model that describes a person. You can also add
images, links and other markdown elements to your documentation.
Feel free to be creative!

- name
  - Type: string
  - Description: Name of the person
- age
  - Type: integer
  - Description: Age of the person

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Person",
  "description": "This is a simple data model that describes a person [...]",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the person"
    },
    "age": {
      "type": "integer",
      "description": "Age of the person"
    }
  },
  "required": ["name", "age"]
}

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="person">
    <xs:annotation>
      <xs:documentation>
        This is a simple data model that describes a person [...]
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="name" type="xs:string">
          <xs:annotation>
            <xs:documentation>Name of the person</xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:element name="age" type="xs:integer">
          <xs:annotation>
            <xs:documentation>Age of the person</xs:documentation>
          </xs:annotation>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

All three formats describe the same data model, but the markdown version offers more readability compared to the JSON and XML versions. In fact, you can even add text/image documentation to any part of your data model and thus communicate the purpose of the data model to other users. The MD-Models library will recognize non-structural elements that are not part of the data model and will not include them in the generated outputs.

Want to learn more? Check out the syntax documentation!

How to use

The MD-Models library is available as a Rust library/binary and can be used to convert and validate markdown data models. We currently support the following templates:

• JSON Schema
• XML Schema Definition (XSD)
• ShEx
• SHACL
• Python-Dataclasses
• Python-Pydantic
• Typescript Interfaces
• Markdown Documentation

We are planning to add more templates in the future. If you have a specific template in mind, feel free to open an issue or a pull request. Alternatively, you can also write your own template and use it with the MD-Models library.

Want to learn more? Check out the library documentation!