adobe / jsonschema2md Goto Github PK

View Code? Open in Web Editor NEW

586.0 43.0 148.0 4.74 MB

Convert Complex JSON Schemas into Markdown Documentation

License: Apache License 2.0

JavaScript 100.00%

json-schema markdown

jsonschema2md's People

Contributors

Stargazers

Watchers

Forkers

kgera man0s adobeatadobe chrisdostert anjankaur asteed jalagari robvenn adammagaluk malsmith andyogo hugorper relequestual walkvanja uglykid73 swvitaliy gerrit91 agdolla vickychijwani hfraser kmp1 sthagen markdemich arsentyev gcallaghan totoketchup evaneus sd2e dskvr markwilk rbuckland dalavancloud addynaikvh fmeschbe brianwendt vitorespindola alanfoster javagl millerdrew skyzyx jhuntoo tomcollins dapplion grv87 digidem oliviachang29 claymore1337 ekline-expnet matthiaspichler koraa pedromorgan aarefiev desh-se tsurdilo vchandra-adobe gqswang luizfernandolopes gnarco pombredanne brad-larson joemitchard ben-foster-cko nikolayhx carlo-quinonez aghassi brainsetbv elliotfehr amahendr eduardoroche arkodg lionheartapplications cndmarcel jjediny sunshowerc grafapps aloisklink lzgit wallybb000 eriesgo alainlecluse fairtracks legytma frogcat sensorup florevallatmrf mackenzie-orange marfeel kagulutw isabella232 thedacheng lucasmarshall ferrangali sondergaard hugoiuri bas080 teq0 autotelic mann-david mdymike bmaranville

jsonschema2md's Issues

The generator does not handle allOf/anyOf/oneOf properly if schemas include properties, and are not references.

This schema:

{
  "$id" : "id",
  "title" : "title",
  "description" : "desc", 
  "type" : "object",

  "allOf": [
    { "properties": {
        "type": { "enum": [ "one", "two" ] }
      }, "required" : ["type"]
    },
    { "properties": {
        "test": { "type": "string" }
      }, "required" : ["test"]
    }
  ]
}

Produces this MarkDown:

# title Schema


desc

| Abstract | Extensible | Status | Custom Properties | Additional Properties | Defined In |
|----------|------------|--------|-------------------|-----------------------|------------|
| Can be instantiated | No | Experimental | Forbidden | Permitted | [protocol2.schema.json](protocol2.schema.json) |

# title Properties

| Property | Type | Required | Defined by |
|----------|------|----------|------------|
| [test](#test) | `string` | **Required** | title (this schema) |
| `*` | any | Additional | this schema *allows* additional properties |

## test


`test`
* is **required**
* type: `string`
* defined in this schema

### test Type


`string`

The "type" property disappears completely. However, this is a valid schema that requires both properties. Additionally, if you change one of the "allOf" elements to "$ref" with the same content, everything works just fine.

The same problem applies to anyOf and oneOf combinations.

No CLI link in contributor guidelines

Sign our CLA at [SOME LINK](no link yet)

That's going to be challenging ;)

Sort order in generated Readme.md is unstable

Some of our builds fail because the sort order of the generated Readme.md file is unstable, e.g. https://circleci.com/gh/adobe/jsonschema2md/162 where the order of Enumerated and Definitions has changed.

List Properties in "Abstract Schemas"

https://git.corp.adobe.com/ankaur/model-spec/blob/exp/newMd/assets/rectangular.schema.md and
https://git.corp.adobe.com/ankaur/model-spec/blob/exp/newMd/content/content.schema.md are examples of "Abstract Schemas", i.e. Schemas that cannot be instantiated directly.

In the generated documentation, we should

still list all the properties that are defined in the definitions block
in the description: point out that this is an abstract schema

Feature: JSON-LD Output

What did you expect to happen

I would like to generate JSON-LD files from the JSON Schema specification. These JSON-LD files should provide additional, optional metadata that stock JSON Schema cannot express.

(suggested by @fmeschbe)

Support "identifiable" attribute

We have certain schemas that have an @id attribute, i.e. that are directly addressable, and others that are not. It would make sense to call this out in the documentation.

Support enum and meta:enum

For a property that has enum values, possible values should be listed like this:

Permitted values are:

- `value1`
- `value2`
- `value3`

Other values are not allowed.

For a property that has meta:enum values as an array, possible values should be listed like this:

Known values are:

- `value1`
- `value2`
- `value3`

Other values are permitted, but might not be understood by implementations.

For a property that has meta:enum values as a map, possible values should be listed like this:

Known values are:

- `value1` - description of value1
- `value2` - description of value2
- `value3` - description of value3

Other values are permitted, but might not be understood by implementations.

For a property that has meta:enum values as a map and enum, possible values should be listed like this:

Permitted values are:

- `value1` - description of value1
- `value2` - description of value2
- `value3` - description of value3

Other values are not allowed.

Add a README.md file in the output directory

This should make browsing listings of generated schemas easier. The generation of the README file should be enabled through an option.

Allow alternative extensions

It would be really nice to allow other extensions besides .schema.json. This is not at all standard, and AFAICT the most common recommendation is to simply use .json. It'd be nice if this was an option on the CLI.

EJS is escaping some markdown

e.g. the > for block quotes as seen here: https://github.com/adobe/xdm/blob/master/docs/reference/content/content.schema.md

Fix: use <%- foo.bar %> instead

CI/CD: publish to npmjs on green commits to master

What do you expect to happen

It would be super radical if on successful commits to master, we automatically published the package to Adobe's artifactory instance.

Context

Had a conversation with @trieloff on Slack about this feature.

default isn't supported

What did you do

I wrote a bunch of draft-v4 schemas and used the default keyword.
Then i npm i --save-dev @adobe/jsonschema2md, which resulted in:

{
  "devDependencies": {
    "@adobe/jsonschema2md": "^1.0.5-SNAPSHOT.190",
  }
}

What did you expect to happen

I expect it to be visible in the generated markdown.

What happened

Not a single default value shows up.

Note: I run all my schemas through ajv to validate them - which are all fine.

What's your environment

Operating System: Mac OS X El Capitan
node.js version: v9.4.0

Do you have example files:

Sure, I even have a PR of a public repo.

For this schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$id": "http://www.axa.ch/schemas/types/event.json",

  "type": "object",
  "title": "Event",
  "description": "Any event to be forwarded/ajaxed to Appway's BPM engine.",

  "additionalProperties": false,
  "required": ["eventName", "eventValue", "skipValidationPhase", "triggered"],
  "properties": {
    "eventName": {
      "type": "string",
      "title": "Event name",
      "description": "The name of the event.",
      "enum": ["onChange", "onClick"],
      "default": "onClick"
    },
    "eventValue": {
      "type": "string",
      "title": "Event value",
      "description": "The kind of action to handle the new value (actually value is in pageValues).",
      "enum": ["back", "next", "reload", "cancel", "default"],
      "default": "default"
    },
    "skipValidationPhase": {
      "type": "boolean",
      "title": "Skip Validation Phase",
      "description": "Whether or not failing validation is ignored by this event.",
      "default": "false"
    },
    "triggered": {
      "type": "boolean",
      "title": "Triggered",
      "description": "Is set if this event was dispatched.",
      "default": "false"
    }
  }
}

I'm getting following Markdown

# Event Schema

http://www.axa.ch/schemas/types/event.json


Any event to be forwarded/ajaxed to Appway's BPM engine.

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Defined In |
|----------|------------|--------|--------------|-------------------|-----------------------|------------|
| Can be instantiated | No | Experimental | No | Forbidden | Forbidden | [types/event.json](types/event.json) |

# Event Properties

| Property | Type | Required | Defined by |
|----------|------|----------|------------|
| [eventName](#eventname) | `enum` | **Required** | Event (this schema) |
| [eventValue](#eventvalue) | `enum` | **Required** | Event (this schema) |
| [skipValidationPhase](#skipvalidationphase) | `boolean` | **Required** | Event (this schema) |
| [triggered](#triggered) | `boolean` | **Required** | Event (this schema) |

## eventName
### Event name

The name of the event.

`eventName`
* is **required**
* type: `enum`
* defined in this schema

The value of this property **must** be equal to one of the [known values below](#eventname-known-values).

### eventName Known Values
| Value | Description |
|-------|-------------|
| `onChange` |  |
| `onClick` |  |




## eventValue
### Event value

The kind of action to handle the new value (actually value is in pageValues).

`eventValue`
* is **required**
* type: `enum`
* defined in this schema

The value of this property **must** be equal to one of the [known values below](#eventvalue-known-values).

### eventValue Known Values
| Value | Description |
|-------|-------------|
| `back` |  |
| `next` |  |
| `reload` |  |
| `cancel` |  |
| `default` |  |




## skipValidationPhase
### Skip Validation Phase

Whether or not failing validation is ignored by this event.

`skipValidationPhase`
* is **required**
* type: `boolean`
* defined in this schema

### skipValidationPhase Type


`boolean`





## triggered
### Triggered

Is set if this event was dispatched.

`triggered`
* is **required**
* type: `boolean`
* defined in this schema

### triggered Type


`boolean`

List status in generated README

If we know the status, we should show it in the README, so that on scanning the list, you can easily get an overview over the experimental and stable schemas.

Handle `additionalItems` and arrays that specify schema order.

Right now, we only handle arrays where items is a schema. The JSON Schema spec also allows items to be an array of schemas. In this case, validation succeeds only if each element in the array validates against the corresponding schema in the items array.

If additionalItems is absent, no additional items are allowed. If it is present, all additional items in the array must follow this schema.

Optional JSON schema output

As mentioned in #43 it would be nice to make the output of JSON schema's optional (which implies no output by default) or at least configurable.

I think it would be easiest to implement by making it optional, so if the -x path/to/schema-output flag is not set, there would be no output, this doesn't require additional CLI arguments but it's a bit of a breaking change compared to previous versions...

Use template-literal instead of EJS

Template Literal is fastest, smallest and simplest template engine, because it use JS's literal template feature.

It's 55 times faster than EJS, and it also use less CPU and RAM ressources, so it may be a good idea to use it instead of EJS 😀

Remove dead `topSchema.ejs`

Since #16 came through, this is dead code and can be removed.

Better handling of simple objects inside an array

https://github.com/adobe/xdm/blob/jsonschema2md-example/docs/reference/assets/asset.schema.md#xdmaliasids-type

Don't throw the unknown type error and fall back to printing the schema, instead show the properties allowed.

Support "status" attribute

In adobe/xdm#161 we introduce a new meta:status property. This property should show up in the metadata table for each schema, so that consumers can easily find out how stable a pre-1.0 schema is.

Schema Hierarchy lists all references, not just inclusions

What did you do

https://github.com/adobe/xdm/blob/master/docs/reference/context/experienceevent.schema.md

What did you expect to happen

Only to list the references that ExperienceEvent is actually importing, not referring to.

What happened

It listed all references

Use proper Headlines

Don't use bold for headlines.

refs in items of array do not work at root level

What did you do

I define an array and used $refs for all it's items.

What did you expect to happen

I expected a nice list of all linked references.

What happened

Nothing displayed

What's your environment

Operating System: Mac OS X El Capitan
node.js version: v9.4.0

Do you have example files:

Sure, I even have a PR of a public repo.

For this schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$id": "http://www.axa.ch/schemas/types/children.json",

  "type": "array",
  "title": "Children",
  "description": "Components rendered within a Component.",

  "additionalItems": false,
  "items": [
    { "$ref": "http://www.axa.ch/schemas/components/Autocomplete.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/BulletRadioButtons.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Button.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Checkbox.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Datepicker.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Dropdown.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Error.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Icon.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Link.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/List.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/ListItem.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Map.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Markdown.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/ModalDialog.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/MultipleSelectList.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/MultipleSelectListItem.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/ProcessEnding.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/SegmentedRadioButtons.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/SelectList.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/SelectListItem.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Textarea.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Textfield.json#" },
    { "$ref": "http://www.axa.ch/schemas/components/Typo.json#" }
  ]
}

I'm getting following Markdown

# Children Schema

http://www.axa.ch/schemas/types/children.json


Components rendered within a Component.

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Defined In |
|----------|------------|--------|--------------|-------------------|-----------------------|------------|
| Can be instantiated | No | Experimental | No | Forbidden | Permitted | [types/children.json](types/children.json) |

Handle patternProperties

patternProperties are currently ignored, but should be listed.

Improve Visualization of Regular Expressions

Maybe we can use something like this: https://www.npmjs.com/package/@kogai/regex-railroad-diagram

To visualize complex regular expressions.

Irritating double dividers when no metadata is present

What did you do

run jsonschema2md on XDM
node cli.js -o ../xdm/docs/reference -d ../xdm/schemas

What did you expect to happen

https://github.com/adobe/xdm/blob/jsonschema2md-example/docs/reference/assets/artboard.schema.md to look nice.

What happened

There are two header lines that are unnecessary.

Group should show the full path, not just the fragment to $ref

https://github.com/adobe/xdm/blob/jsonschema2md-example/docs/reference/assets/copyright-owner.schema.md#copyright-owner-definitions

You want the Group property to be copyable.

Link to Json schema(.json) does not work in header table(DefinedIn column)

What did you do

Click on the .json link for the schema in DefinedIn column

What did you expect to happen

Open correct .json file of the schema

What happened

Error 404(Incorrect link)

Do you have example files:

This is for all .md files actually but examples below
In Examples: https://github.com/adobe/jsonschema2md/blob/master/examples/docs/arrays.schema.md
In XDM: https://github.com/adobe/xdm/blob/master/docs/reference/assets/aggregated-asset.schema.md

Header Generation fails in XDM for aggregated-asset

https://circleci.com/gh/adobe/xdm/2305

XDM is using version 1.0.5 and failing:

> shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md --link-extensible extensions.md --link-status status.md --link-id --link-custom extensions.md --link-additional extensions.md

info: output directory: /home/circleci/repo/docs/reference
info: finished reading all *.schema.json files in /home/circleci/repo/schemas, beginning processing….
/home/circleci/repo/schemas/assets/aggregated-asset.schema.json
error:  TypeError: Path must be a string. Received true
    at assertPath (path.js:7:11)
    at Object.relative (path.js:1227:5)
    at link (/home/circleci/repo/node_modules/@adobe/jsonschema2md/lib/header.js:80:17)
    at headers (/home/circleci/repo/node_modules/@adobe/jsonschema2md/lib/header.js:105:50)
    at generateMarkdown (/home/circleci/repo/node_modules/@adobe/jsonschema2md/lib/markdownWriter.js:154:14)
    at Schema.getExamples.then.then.then.object (/home/circleci/repo/node_modules/@adobe/jsonschema2md/lib/schema.js:424:11)

Sort properties alphabetically

Not in document (or random) order.

Provide Examples

We should have a small set of example schemas that can be used for integration tests, and to demonstrate new features.

known values of enum empty

What did you do

I defined enum within a nested schema and the values get lost somehow.

What did you expect to happen

I expect that all values show up the Known Values table.

What happened

None are shown.

Note: I run all my schemas through ajv to validate them - which are all fine.

What's your environment

Operating System: Mac OS X El Capitan
node.js version: v9.4.0

Do you have example files:

Sure, I even have a PR of a public repo.

For this schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$id": "http://www.axa.ch/schemas/components/Typo.json",

  "type": "object",
  "title": "Typo",
  "description": "Renders a Typo.",

  "additionalProperties": false,
  "required": ["component"],
  "properties": {
    "component": {
      "allOf": [
        { "$ref": "http://www.axa.ch/schemas/types/component.json#" },
        { "enum": ["Typo"] }
      ]
    },

    "properties": {
      "type": "object",
      "title": "Properties",
      "description": "Properties of Typo.",

      "additionalProperties": false,
      "properties": {
        "value": {
          "type": "string",
          "title": "Value",
          "description": "The text to be displayed."
        }
      }
    },

    "style": {
      "type": "object",
      "title": "Style",
      "description": "Style of Typo.",

      "additionalProperties": false,
      "properties": {
        "title": {
          "type": "boolean",
          "title": "Title",
          "description": "Whether or not the text is a heading.",
          "default": false
        },
        "type": {
          "type": "string",
          "title": "Type",
          "description": "The type of heading to be used for display.",
          "enum": ["main", "page", "slice", "small-module"],
          "default": "main"
        },
        "publico": {
          "type": "boolean",
          "title": "Publico",
          "description": "Whether or not to use the Publico Headline font in favour of Source Sans Pro",
          "default": false
        },
        "size": {
          "type": "string",
          "title": "Size",
          "description": "Size of Typo.",
          "enum": ["semibold", "bold", "normal"],
          "default": "normal"
        },
        "align": {
          "type": "string",
          "title": "Align",
          "description": "Set CSS text-align accordingly.",
          "enum": ["left", "right", "center"],
          "default": "left"
        },
        "longer": {
          "type": "boolean",
          "title": "Longer",
          "description": "Whether or not longer style is used for display.",
          "default": false
        },
        "secondary": {
          "type": "boolean",
          "title": "Secondary",
          "description": "Whether or not to display text according to AXA.ch style guide's secondary definition.",
          "default": false
        },
        "secondRow": {
          "type": "boolean",
          "title": "Second Row",
          "description": "Whether or not to use smaller margin between to show that two typos belong together.",
          "default": false
        },
        "color": {
          "type": "string",
          "title": "Color",
          "description": "Color of Typo.",
          "enum": ["red", "blue", "black"],
          "default": "black"
        }
      }
    }
  }
}

I'm getting following Markdown

# Typo Schema

http://www.axa.ch/schemas/components/Typo.json


Renders a Typo.

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Defined In |
|----------|------------|--------|--------------|-------------------|-----------------------|------------|
| Can be instantiated | No | Experimental | No | Forbidden | Forbidden | [components/Typo.json](components/Typo.json) |

# Typo Properties

| Property | Type | Required | Defined by |
|----------|------|----------|------------|
| [component](#component) | complex | **Required** | Typo (this schema) |
| [properties](#properties) | `object` | Optional | Typo (this schema) |
| [style](#style) | `object` | Optional | Typo (this schema) |

## component


`component`
* is **required**
* type: complex
* defined in this schema

### component Type


**All** of the following *requirements* need to be fulfilled.


#### Requirement 1


* []() – `http://www.axa.ch/schemas/types/component.json#`


#### Requirement 2







## properties
### Properties

Properties of Typo.

`properties`
* is optional
* type: `object`
* defined in this schema

### properties Type


`object` with following properties:


| Property | Type | Required
|----------|------|----------|
| `value`| string | Optional | 



#### value
##### Value

The text to be displayed.

`value`
* is optional
* type: `string`

##### value Type


`string`











## style
### Style

Style of Typo.

`style`
* is optional
* type: `object`
* defined in this schema

### style Type


`object` with following properties:


| Property | Type | Required
|----------|------|----------|
| `align`| string | Optional | 
| `color`| string | Optional | 
| `longer`| boolean | Optional | 
| `publico`| boolean | Optional | 
| `secondRow`| boolean | Optional | 
| `secondary`| boolean | Optional | 
| `size`| string | Optional | 
| `title`| boolean | Optional | 
| `type`| string | Optional | 



#### align
##### Align

Set CSS text-align accordingly.

`align`
* is optional
* type: `string`

The value of this property **must** be equal to one of the [known values below](#style-known-values).

##### align Known Values
| Value | Description |
|-------|-------------|






#### color
##### Color

Color of Typo.

`color`
* is optional
* type: `string`

The value of this property **must** be equal to one of the [known values below](#style-known-values).

##### color Known Values
| Value | Description |
|-------|-------------|






#### longer
##### Longer

Whether or not longer style is used for display.

`longer`
* is optional
* type: `boolean`

##### longer Type


`boolean`







#### publico
##### Publico

Whether or not to use the Publico Headline font in favour of Source Sans Pro

`publico`
* is optional
* type: `boolean`

##### publico Type


`boolean`







#### secondRow
##### Second Row

Whether or not to use smaller margin between to show that two typos belong together.

`secondRow`
* is optional
* type: `boolean`

##### secondRow Type


`boolean`







#### secondary
##### Secondary

Whether or not to display text according to AXA.ch style guide's secondary definition.

`secondary`
* is optional
* type: `boolean`

##### secondary Type


`boolean`







#### size
##### Size

Size of Typo.

`size`
* is optional
* type: `string`

The value of this property **must** be equal to one of the [known values below](#style-known-values).

##### size Known Values
| Value | Description |
|-------|-------------|






#### title
##### Title

Whether or not the text is a heading.

`title`
* is optional
* type: `boolean`

##### title Type


`boolean`







#### type
##### Type

The type of heading to be used for display.

`type`
* is optional
* type: `string`

The value of this property **must** be equal to one of the [known values below](#style-known-values).

##### type Known Values
| Value | Description |
|-------|-------------|

Support not keyword

The not keyword is currently not understood.

Point out if a schema is extensible

If this pull request comes through, we should include a note for every schema if it is extensible or not:
see also: https://git.corp.adobe.com/AdobeCloudPlatform/models/pull/43/files#diff-4d7cdf0fc878af052e8b73d41dd8c7ddR48

Better handling of property names that are indistinguishable for GitHub

Example: id and @id in the same schema will get turned into #id and #id-1 by GitHub.

This can be observed here: https://github.com/adobe/jsonschema2md/blob/master/examples/docs/deepextending.schema.md

When a schema fails validation it's not clear which schema failed

What did you do

I ran jsonschema2md --input /path/to/dir ...

What did you expect to happen

I expected it to convert my schemas but ...

What happened

I got this error:

/usr/local/jsonschema2md-1.0.2/node_modules/ajv/lib/ajv.js:188
    else throw new Error(message);
         ^

Error: schema is invalid: data.properties['processor'].required should NOT have less than 1 items
    at Ajv.validateSchema (/usr/local/jsonschema2md-1.0.2/node_modules/ajv/lib/ajv.js:188:16)
    at Ajv._addSchema (/usr/local/jsonschema2md-1.0.2/node_modules/ajv/lib/ajv.js:317:10)
    at Ajv.addSchema (/usr/local/jsonschema2md-1.0.2/node_modules/ajv/lib/ajv.js:141:29)
    at ReaddirpReadable.readdirp.on.entry (/usr/local/jsonschema2md-1.0.2/cli.js:86:11)
    at emitOne (events.js:116:13)
    at ReaddirpReadable.emit (events.js:211:7)
    at addChunk (/usr/local/jsonschema2md-1.0.2/node_modules/readable-stream/lib/_stream_readable.js:291:12)
    at readableAddChunk (/usr/local/jsonschema2md-1.0.2/node_modules/readable-stream/lib/_stream_readable.js:278:11)
    at ReaddirpReadable.Readable.push (/usr/local/jsonschema2md-1.0.2/node_modules/readable-stream/lib/_stream_readable.js:245:10)
    at ReaddirpReadable.proto._processEntry (/usr/local/jsonschema2md-1.0.2/node_modules/readdirp/stream-api.js:52:8)
    at /usr/local/jsonschema2md-1.0.2/node_modules/readdirp/readdirp.js:243:15
    at Array.forEach (<anonymous>)
    at /usr/local/jsonschema2md-1.0.2/node_modules/readdirp/readdirp.js:241:12
    at /usr/local/jsonschema2md-1.0.2/node_modules/readdirp/readdirp.js:199:38
    at /usr/local/jsonschema2md-1.0.2/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqWrap.oncomplete (fs.js:153:5)

What's your environment

Not relevant

The problem is really in the ajv library, but this tool can ameliorate it by indicating what schema it's processing in cli.js before calling ajv.addSchema.

Template error when description is missing

Cannot read property 'replace' of undefined in templates/md/header.ejs:15

 <%- schema.description.replace(/\n/g, '\n\n') %>

This could be fixed by just checking if there is a description

<% if (schema.description!==undefined) { %>
<%- schema.description.replace(/\n/g, '\n\n') %>
<% } %>

description.md line breaks get stripped out

What did you do

run jsonschema2md on XDM
node cli.js -o ../xdm/docs/reference -d ../xdm/schemas

What did you expect to happen

https://github.com/adobe/xdm/blob/jsonschema2md-example/docs/reference/assets/asset.schema.md#asset-schema to have a well-formatted description

What did happen

There are no more line breaks in the description, making it hard to read.

Remove logic from ejs templates

The ejs templates for Markdown generation are quite heavy. It would be ideal to just pass pretty-printed JSON objects that don't require much formatting instead.

Support meta: example

The meta:example property is a either a single example, or a list of examples. They should be listed using three backticks as code examples.

Formatting Issues for Imported Descriptions

@ankaur thanks for #23 – I'm reviewing the example output you've provided in https://git.corp.adobe.com/ankaur/model-spec/tree/exp/newMd

https://git.corp.adobe.com/ankaur/model-spec/edit/exp/newMd/assets/asset.schema.md (line 11): the line breaks in the imported description.md get mangled. Markdown needs two line break to create a proper paragraph

Handle additionalProperties

additionalProperties should be handled.

-x command line option is ignored

$ node cli.js -d examples/schemas -o examples/docs -x examples/generated-schemas

Generates schemas in examples/docs/_newSchema, not in examples/generated-schemas

Link to documentation/explanation for schema attributes

abstract
extensible
etc.

Support "singleton" schema attribute

The "Abstract" field should also support "Singleton" for schemas where every property is a const

Links are not lowercased

https://github.com/adobe/xdm/blob/master/docs/reference/assets/asset.schema.md#xmpmachineKeywords should be https://github.com/adobe/xdm/blob/master/docs/reference/assets/asset.schema.md#xmpmachinekeywords

unknown type object

i don't quite understand why settings renders correctly but collaborators yields an Unknown type object

i can produce this error with any child object under settings. is there something wrong w/ my json schema that would cause this?

json:

{
    "$id": "test.json",
    "$schema": "http://json-schema.org/draft-06/schema",
    "title": "test",
    "type": "object",
    "properties": {
        "settings": {
            "description": "settings",
            "type": "object",
            "properties": {
                "collaborators": {
                    "description": "collaborators",
                    "type": "object",
                    "patternProperties": {
                        ".*": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    },
    "additionalProperties": false
}

resulting markdown:

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Defined In |
|----------|------------|--------|--------------|-------------------|-----------------------|------------|
| Can be instantiated | No | Experimental | No | Forbidden | Forbidden |  |

# test Properties

| Property | Type | Required | Defined by |
|----------|------|----------|------------|
| [settings](#settings) | `object` | Optional | test (this schema) |

## settings

settings

`settings`
* is optional
* type: `object`
* defined in this schema

### settings Type


`object` with following properties:


| Property | Type | Required
|----------|------|----------|
| `collaborators`| object | Optional | 



#### collaborators

collaborators

`collaborators`
* is optional
* type: `object`

##### collaborators Type

Unknown type `object`.

```json
{
  "description": "collaborators",
  "type": "object",
  "patternProperties": {
    ".*": {
      "type": "string"
    }
  },
  "simpletype": "`object`"
}

List and link schemas that are referenced

As we are using definitions and $ref constructs to structure schemas, the generated documentation should list all the schemas that are being referenced, with name and link to the accompanying Markdown file.

e.g.

Image is based on:
* [Asset](asset.md)
  * [Extensible](../base/extensibility.md)

If a schema (like extensibility) is referenced by multiple schemas, it should be listed only the first time to avoid endless and circular lists.

Documentation should list where a property has been declared

If a property has been declared in a referenced schema, it should be included in full in the current document's documentation, with a note explaining that it is referenced from another schema.

For instance, for Image:

## modify_date

`modify_date` is referenced from [Asset](asset.md#modify_date)

Unable to handle nested object types

See https://github.com/adobe/jsonschema2md/blob/master/examples/docs/complex.schema.md#refabstract-type

Type should be object and just like for the array, a nested-properties and nested-property should be included.

GitHub doesn't show links for property names with colon

What did you do

run jsonschema2md on XDM
node cli.js -o ../xdm/docs/reference -d ../xdm/schemas

What did you expect to happen

https://github.com/adobe/xdm/blob/jsonschema2md-example/docs/reference/assets/artboard.schema.md to have links to the referenced schema

What happened

GitHub ignored the links because the fragment identifier contained a :

Do you have example files:

I'm getting following Markdown

[Rectangular Object (measured in variable unit)](variable-unit-rectangular.schema.md#stLayer:unit)

correct would be:

[Rectangular Object (measured in variable unit)](variable-unit-rectangular.schema.md#stlayerunit)

(lowercase, all special characters stripped)

adobe / jsonschema2md Goto Github PK

jsonschema2md's People

Contributors

Stargazers

Watchers

Forkers

jsonschema2md's Issues

What did you expect to happen

What do you expect to happen

Context

What did you do

What did you expect to happen

What happened

What's your environment

Do you have example files:

What did you do

What did you expect to happen

What happened

What did you do

What did you expect to happen

What happened

What's your environment

Do you have example files:

What did you do

What did you expect to happen

What happened

What did you do

What did you expect to happen

What happened

Do you have example files:

What did you do

What did you expect to happen

What happened

What's your environment

Do you have example files:

What did you do

What did you expect to happen

What happened

What's your environment

What did you do

What did you expect to happen

What did happen

What did you do

What did you expect to happen

What happened

Do you have example files:

Recommend Projects

Recommend Topics

Recommend Org

Jobs