Schema Documentation

Introduction

Nadap provides a documenation generation of the data structure, data types, all value limitations and descriptions within a data schema. Currently the documentation can be provided as markdown table with detailed information about data types, default values, restrictions and description or as a nice but short YAML code block.

Nadap supports three documentation methods: - Single - Provides the full schema in one documentation - Split - Provides a list of documentations of the schema based on a given level - Structured - Provides a list of documentations of the schema based on a given structure

Single Documentation

Nadap can create a documentation of the schema in single markdown table or in a single YAML string.

Single - Python Code Example

import nadap

schema_definition = {
  "root": {
    "type": "dict",
    "keys": {
      "attr1": "int",
      "attr2": {
        "type": "list",
        "elements": "str"
      }
    }
  }
}

n = nadap.Nadap()
schema = n.load_schema_definition(schema_definition)
markdown_table_string = schema.doc(fmt="markdown")
yaml_doc_string = schema.doc(fmt="yaml")

Single - Example

Schema definition:

custom_data_types:
  cdt_test:
    type: int
    template: template1
    maximum: 100
root:
  type: dict
  restrictions:
    required: ["id", "name"]
  keys:
    id: cdt_test
    name:
      type: str
      template: template1
      default_value: Me
      not_allowed_values: ["nadap", "sucks!"]
    healthy: bool_true
    neighbors:
      type: idlist
      id:
        type: str
        template: template1
        description: Neighbor's name
      elements:
          type: dict
          restrictions:
            xor_required:
              - ["likes", "loves"]
          keys:
              score:
                type: float
                minimum: 0.0
                maximum: 10.0
              likes:
                type: list
                elements: str
                minimum: 2
              loves:
                type: list
                elements: str
                minimum: 1
templates:
  template1:
    minimum: 1
    maximum: 255

Markdown Table:

Variable	Type	Default	Restrictions	Description
id	`int`		required
name	`str`	Me	required
healthy	`bool`	True
neighbors	`dict`
< str >			min length: 1 max length: 255	Neighbor's name
score	`float`
likes	`list[str]`		excludes: loves
- < str >	`str`
loves	`list[str]`		excludes: likes
- < str >	`str`

YAML:

id: <int>
name: <str>
healthy: <bool>
neighbors:
  <str>:
    score: <float>
    likes:
      - <str>
    loves:
      - <str>

Split Documentation

Nadap can split the documentation of the schema into chunks based on a given iteration level. Nadap iteratively splits the schema based on dicts and their keys. Thus, root data type must be a dict. Nadap returns a dictionary with path to key as keys and documentation snippets as values.

| Note: Default level is 0 (split root dictionary into keys only)

Split - Python Code Example

import nadap

schema_definition = {
  "root": {
    "type": "dict",
    "keys": {
      "attr1": "int",
      "attr2": {
        "type": "list",
        "elements": "str"
      }
    }
  }
}

n = nadap.Nadap()
schema = n.load_schema_definition(schema_definition)
markdown_tables_dict = schema.doc_sections(fmt="markdown", level=1)
yaml_dict = schema.doc_sections(fmt="yaml", level=1)

Split - Example Schema

Schema definition:

root:
  type: dict
  restrictions:
    required: ["id", "name"]
  keys:
    id: int
    name:
      type: str
      default_value: Me
      not_allowed_values: ["nadap", "sucks!"]
    information:
      type: dict
      keys:
        health:
          type: dict
          keys:
            ill: bool_false
            blood_group: str
            age: int
        education:
          type: dict
          keys:
            elementary_school: str
            high_school: str
    neighbors:
      type: idlist
      id:
        type: str
        description: Neighbor's name
      elements:
          type: dict
          restrictions:
            xor_required:
              - ["likes", "loves"]
          keys:
              score:
                type: float
                minimum: 0.0
                maximum: 10.0
              likes:
                type: list
                elements: str
                minimum: 2
              loves:
                type: list
                elements: str
                minimum: 1

Markdown Tables with level=0

Key: id

Value:

Variable	Type	Default	Restrictions	Description
id	`int`		required

Key: name

Value:

Variable	Type	Default	Restrictions	Description
name	`str`	Me	required not allowed strings: - `nadap` - `sucks!`

Key: information

Value:

Variable	Type	Default
information	`dict`
health	`dict`
ill	`bool`	False
blood_group	`str`
age	`int`
education	`dict`
elementary_school	`str`
high_school	`str`

Key: neighbors

Value:

Variable	Type	Restrictions	Description
neighbors	`dict`
< str >			Neighbor's name
score	`float`	min: 0.0 max: 10.0
likes	`list[str]`	excludes: loves min length: 2
- < str >	`str`
loves	`list[str]`	excludes: likes min length: 1
- < str >	`str`

YAML Snippets with level=0

key: id

value:

id: <int>

key: name

value:

name: <str>

key: information

value:

information:
  health:
    ill: <bool>
    blood_group: <str>
    age: <int>
  education:
    elementary_school: <str>
    high_school: <str>

key: neighbors

value:

neighbors:
  <str>:
    score: <float>
    likes:
      - <str>
    loves:
      - <str>

Markdown Tables with level=1

key: id

value:

Variable	Type	Default	Restrictions	Description
id	`int`		required

key: name

value:

Variable	Type	Default	Restrictions	Description
name	`str`	Me	required not allowed strings: - `nadap` - `sucks!`

key: information.health

value:

Variable	Type	Default
information	`dict`
health	`dict`
ill	`bool`	False
blood_group	`str`
age	`int`

key: information.education

value:

Variable	Type	Default	Restrictions	Description
information	`dict`
education	`dict`
elementary_school	`str`
high_school	`str`

key: neighbors

value:

Variable	Type	Restrictions	Description
neighbors	`dict`
< str >			Neighbor's name
score	`float`	min: 0.0 max: 10.0
likes	`list[str]`	excludes: loves min length: 2
- < str >	`str`
loves	`list[str]`	excludes: likes min length: 1
- < str >	`str`

YAML Snippets with level=1

key: id

value:

id: <int>

key: name

value:

name: <str>

key: information.health

value:

information:
  health:
    ill: <bool>
    blood_group: <str>
    age: <int>

key: information.education

value:

information:
  education:
    elementary_school: <str>
    high_school: <str>

key: neighbors

value:

neighbors:
  <str>:
    score: <float>
    likes:
      - <str>
    loves:
      - <str>

Structured Documentation

Nadap can split the documentation of the schema into chunks based on a given structure.

The structure is a list of strings (representing keys in a dict data type) or nested dictionary with list of strings as values. Keys also represents keys in a dict data type.

Nadap returns a tuple. First tuple element contains as dictionary with path to key as keys and documentation snippets as values. Second tuple element contains a documentation snippet for all non-matching data structure in the schema.

Structured - Python Code Example

import nadap

schema_definition = {
  "root": {
    "type": "dict",
    "keys": {
      "attr1": "int",
      "attr2": {
        "type": "list",
        "elements": "str"
      }
    }
  }
}

n = nadap.Nadap()
schema = n.load_schema_definition(schema_definition)
structured_markdown_tables_dict, remaining_markdown_table = schema.structured_doc(fmt="markdown", structure=["attr1"])
structured_yaml_dict, remaining_yaml = schema.doc_sections(fmt="yaml", structure=["attr1"])

Structured - Example

Schema definition

root:
  type: dict
  keys:
    name: str
    information:
      type: dict
      keys:
        health:
          type: dict
          keys:
            ill: bool_false
            blood_group: str
            age: int
        education:
          type: dict
          keys:
            elementary_school: str
            high_school: str
    neighbors:
      type: list
      elements: str

Intended documentation structure

information:
  health:
    - age

Markdown Tables

key: information

value:

Variable	Type	Default	Restrictions	Description
information	`dict`
education	`dict`
elementary_school	`str`
high_school	`str`

key: information.health

value:

Variable	Type	Default
information	`dict`
health	`dict`
ill	`bool`	False
blood_group	`str`

key: information.health.age

value:

Variable	Type	Default	Restrictions	Description
information	`dict`
health	`dict`
age	`int`

Markdown Table for remaining data structure

Variable	Type	Default	Restrictions	Description
name	`str`
neighbors	`list[str]`
- < str >	`str`

YAML Snippets

key: information

value:

information:
  education:
    elementary_school: <str>
    high_school: <str>

key: information.health

value:

information:
  health:
    ill: <bool>
    blood_group: <str>

key: information.health.age

value:

information:
  health:
    age: <int>

YAML for remaining data structure

name: <str>
neighbors:
  - <str>

Schema Documentation

Table of Contents

Introduction

Single Documentation

Single - Python Code Example

Single - Example

Split Documentation

Split - Python Code Example

Split - Example Schema

Markdown Tables with level=0

YAML Snippets with level=0

Markdown Tables with level=1

YAML Snippets with level=1

Structured Documentation

Structured - Python Code Example

Structured - Example

Schema definition

Intended documentation structure

Markdown Tables

YAML Snippets