Convert JSON Schemas to simple, human-readable Markdown documentation. Repo archived in favor of fork: sbrunner/jsonschema2md2
Home Page: https://github.com/sbrunner/jsonschema2md2
License: Apache License 2.0
Support for required properties is not present.
Hi, I've checked that there is no support for oneOf clauses. Is it in the roadmap?
Not sure what exactly causes it but it fails on a valid schema with this:
raise TypeError(
TypeError: Non-object type found in properties list: `Items: [{'type': 'number'}, {'type': 'number'}]`.Schema
{
"title": "DfSchema",
"type": "object",
"properties": {
"metadata": {
"title": "Metadata",
"description": "optional metadata, including version and protocol version",
"default": {
"protocol_version": 2.0,
"version": "2022-07-10",
"custom_settings": null
},
"allOf": [
{
"$ref": "#/definitions/MetaData"
}
]
},
"shape": {
"title": "Shape",
"description": "shape expectations",
"allOf": [
{
"$ref": "#/definitions/ShapeSchema"
}
]
},
"columns": {
"title": "Columns",
"description": "columns expectations",
"default": [],
"type": "array",
"items": {
"$ref": "#/definitions/ColSchema"
}
},
"strict_column_set": {
"title": "Strict Column Set",
"description": "if true, won't allow any columns not defined in the schema",
"default": false,
"type": "boolean"
},
"subsets": {
"title": "Subsets",
"description": "dataframe subset expectations",
"type": "array",
"items": {
"$ref": "#/definitions/SubsetSchema"
}
}
},
"additionalProperties": false,
"definitions": {
"MetaData": {
"title": "MetaData",
"type": "object",
"properties": {
"protocol_version": {
"title": "Protocol Version",
"description": "protocol version of the schema",
"default": 2.0,
"type": "number"
},
"version": {
"title": "Version",
"description": "version of the schema",
"default": "2022-07-10",
"example": "2022-06-12",
"type": "string"
},
"custom_settings": {
"title": "Custom Settings",
"description": "custom settings. does not affect any logic",
"type": "object"
}
}
},
"ShapeSchema": {
"title": "ShapeSchema",
"type": "object",
"properties": {
"rows": {
"title": "Rows",
"description": "exact number of rows",
"exclusiveMinimum": 0,
"type": "integer"
},
"cols": {
"title": "Cols",
"description": "exact number of columns",
"exclusiveMinimum": 0,
"type": "integer"
},
"max_cols": {
"title": "Max Cols",
"description": "maximum number of columns",
"exclusiveMinimum": 0,
"type": "integer"
},
"min_cols": {
"title": "Min Cols",
"description": "minimum number of columns",
"exclusiveMinimum": 0,
"type": "integer"
},
"max_rows": {
"title": "Max Rows",
"description": "maximum number of rows",
"exclusiveMinimum": 0,
"type": "integer"
},
"min_rows": {
"title": "Min Rows",
"description": "minimum number of rows",
"exclusiveMinimum": 0,
"type": "integer"
}
},
"additionalProperties": false
},
"ValueLimits": {
"title": "ValueLimits",
"type": "object",
"properties": {
"min": {
"title": "Min",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string",
"format": "date-time"
},
{
"type": "string"
}
]
},
"max": {
"title": "Max",
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string",
"format": "date-time"
},
{
"type": "string"
}
]
}
},
"additionalProperties": false
},
"Categorical": {
"title": "Categorical",
"type": "object",
"properties": {
"value_set": {
"title": "Value Set",
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"mode": {
"title": "Mode",
"enum": [
"oneof",
"exact_set",
"include"
],
"type": "string"
},
"unique": {
"title": "Unique",
"description": "if true, the column must contain only unique values",
"default": false,
"type": "boolean"
}
},
"additionalProperties": false
},
"DistributionMetric": {
"title": "DistributionMetric",
"type": "object",
"properties": {
"name": {
"title": "Name",
"enum": [
"mean",
"std",
"median",
"quantile"
],
"type": "string"
},
"range": {
"title": "Range",
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
},
"kwargs": {
"title": "Kwargs",
"description": "Additional arguments for the metric to be passed via **kwargs",
"default": {},
"type": "object"
}
},
"required": [
"name",
"range"
],
"additionalProperties": false
},
"Distribution": {
"title": "Distribution",
"type": "object",
"properties": {
"metrics": {
"title": "Metrics",
"default": [],
"type": "array",
"items": {
"$ref": "#/definitions/DistributionMetric"
}
}
},
"additionalProperties": false
},
"ColSchema": {
"title": "ColSchema",
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "Name of the column",
"type": "string"
},
"dtype": {
"title": "Dtype",
"description": "Data type of the column",
"enum": [
"bool_",
"bool",
"object",
"str",
"character",
"string",
"number",
"numeric",
"float",
"floating",
"integer",
"int",
"int64",
"datetime",
"date",
"timedelta",
"category"
],
"type": "string"
},
"na_limit": {
"title": "Na Limit",
"description": "limit of missing values. If set to true, will raise if all values are empty. If set to a number, will raise if more than that fraction of values are empty (Nan)",
"exclusiveMaximum": 1.0,
"minimum": 0,
"type": "number"
},
"value_limits": {
"title": "Value Limits",
"description": "Value limits for the column",
"allOf": [
{
"$ref": "#/definitions/ValueLimits"
}
]
},
"categorical": {
"title": "Categorical",
"description": "Categorical expectations for the column",
"allOf": [
{
"$ref": "#/definitions/Categorical"
}
]
},
"distribution": {
"title": "Distribution",
"description": "Distribution expectations for the column",
"allOf": [
{
"$ref": "#/definitions/Distribution"
}
]
},
"str_pattern": {
"title": "Str Pattern",
"description": "Regex pattern for string columns. Should pass `pd.Series.str.match`",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
},
"required": [
"name"
],
"additionalProperties": false
},
"SubsetSchema": {
"title": "SubsetSchema",
"description": "Subset is essentially same as DfSchema,\nexcept it is assumed to run validation on a SUBSET of the dataframe.",
"type": "object",
"properties": {
"predicate": {
"title": "Predicate",
"description": "\n predicate to select subset.\n - If string, will be interpreted as query for `df.query()`.\n - If dict, keys should be column names, values should be values to exactly match",
"anyOf": [
{
"type": "object"
},
{
"type": "string"
}
]
},
"shape": {
"title": "Shape",
"description": "shape expectations",
"allOf": [
{
"$ref": "#/definitions/ShapeSchema"
}
]
},
"columns": {
"title": "Columns",
"description": "columns expectations",
"default": [],
"type": "array",
"items": {
"$ref": "#/definitions/ColSchema"
}
},
"strict_column_set": {
"title": "Strict Column Set",
"description": "if true, won't allow any columns not defined in the schema",
"default": false,
"type": "boolean"
}
},
"required": [
"predicate"
],
"additionalProperties": false
}
}
}It seems that tabsize is set to 2 as a constant. However, popular python library python-markdown can only take tab length = 4.
Looking at adding this to conda-forge so can be installed using conda.
I am more than happy to do this.
How I will go about doing it: https://conda-forge.org/docs/maintainer/adding_pkgs.html#step-by-step-instructions
Currently this can't be installed in parallel with other tools like json-schema-for-humans since it requires click 8.
SolverProblemError
Because no versions of jsonschema2md match >0.2.1,<0.3.0
and jsonschema2md (0.2.1) depends on click (>=7,<8), jsonschema2md (>=0.2.1,<0.3.0) requires click (>=7,<8).
And because json-schema-for-humans (0.35.2) depends on click (>=8.0.1,<9.0.0)
and no versions of json-schema-for-humans match >0.35.2,<0.36.0, jsonschema2md (>=0.2.1,<0.3.0) is incompatible with json-schema-for-humans (>=0.35.2,<0.36.0).
So, because schema depends on both json-schema-for-humans (^0.35.2) and jsonschema2md (^0.2.1), version solving failed.
Please update the lockfile.
E.g. here https://github.com/sbrunner/scan-to-paperless/blob/test/config.md
I get Refer to #/definitions/auto_mask but it can be a link.
For that, each definition should have a title...
Are you open that I do a pull request?
Hey,
I find a little bug (maybe) in the example section generation. This section is create without \n between next ligne. This have a bad effect when I use it with Mkdocs (and maybe some other viewer).
Follow the path, I using Mkdocs plugin, base on your python Lib.
Current result :
- **`name`** *(string)*: Your AFS friendly name.
Examples:
```json
{
"afs_global": {
"name": "My Best AFS"
}
}
```
- **`code`** *(string)*
- **`provider`** *(string)*Expected result :
- **`name`** *(string)*: Your AFS friendly name.
Examples:
```json
{
"afs_global": {
"name": "My Best AFS"
}
}
```
- **`code`** *(string)*
- **`provider`** *(string)*Markdown standard require blank arroung code block. https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md#md031
I think you just need to add \n at this end :
jsonschema2md/jsonschema2md.py
Line 95 in 31e2f70
Final result :
f"{example_indentation}```json\n{example_str}\n{example_indentation}```\n\n"
Just tested, I can confirm than this work with mkdocs generator.
Currently the values associated with the default and enum keywords on properties are displayed as their corresponding Python string representations in the Markdown translation. For example
"default": null → Default: None
"default": true → Default: True
"default": "a string" → Default: a string
"enum": ["option 1", "option 2"] → Must be one of: ['option 1', 'option 2']
As these are meant to represent possible values in a JSON file it seem like it would be preferable to use the corresponding JSON string representations, that is for the above examples we would have
"default": null → Default: null
"default": true → Default: true
"default": "a string" → Default: "a string"
"enum": ["option 1", "option 2"] → Must be one of: ["option 1", "option 2"]
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.