Am I correct that the root type can only be object? #73

AndyOGo · 2018-05-24T06:58:08Z

What did you do

I used type: 'array' at the root of my json schema file.

What did you expect to happen

I expected it to be documented.

What happened

nothing related to type array was documented.

What's your environment

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

Do you have example files:

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) |

The text was updated successfully, but these errors were encountered:

AndyOGo · 2018-05-24T07:23:09Z

I just tracked this down and surprisingly it really only handles properties and definitions at the root of a JSON schema - related code:

for properties https://github.com/adobe/jsonschema2md/blob/master/lib/markdownWriter.js#L172-L202
for definition https://github.com/adobe/jsonschema2md/blob/master/lib/markdownWriter.js#L203-L241
thats it!

Being that restrictive, breaks almost all JSON schema features at the root including but not limited to:

type of array, string, number, integer, boolean
even object itself is incomplete, by not supporting patternProperties, required, additionalProperties, etc.
enum
default
basically the whole spec except for properties

AndyOGo · 2018-06-05T11:08:51Z

@trieloff
Do you have some time to look into this?

AndyOGo · 2018-06-19T09:19:56Z

@trieloff
@anjankaur
I really need other types than object available at the root level.
It should be possible to start the recursive computation one level higher.

bryanculver · 2019-04-09T14:49:14Z

I just tracked this down and surprisingly it really only handles properties and definitions at the root of a JSON schema - related code:

for properties https://github.com/adobe/jsonschema2md/blob/master/lib/markdownWriter.js#L172-L202

for definition https://github.com/adobe/jsonschema2md/blob/master/lib/markdownWriter.js#L203-L241

For clarity sake, since this referenced master and not a specific commit the line highlights are no longer correct.

Here are the respective highlights as of the commit in reference:

for properties

jsonschema2md/lib/markdownWriter.js

Lines 172 to 202 in 74db566

    
           if (_.keys(schema.properties).length > 0) { 
        
             //table of contents 
        
             multi.push([ 'properties.ejs', { 
        
               props: requiredProperties(schema.properties, schema.required), 
        
               pprops: _.mapValues(schema.patternProperties, simpletype), 
        
               title: schema.title, 
        
               additional: schema.additionalProperties, 
        
               propertiesSlugs: propertiesSlugs 
        
             } ]); 
        
             //regular properties 
        
             for (let i=0; i<_.keys(schema.properties).length;i++) { 
        
               const name = _.keys(schema.properties).sort()[i]; 
        
               multi.push( [ 'property.ejs', { 
        
                 name: name, 
        
                 required: schema.required ? schema.required.includes(name) : false, 
        
                 examples: stringifyExamples(schema.properties[name]['examples']), 
        
                 ejs: ejsRender, 
        
                 schema: simpletype(schema.properties[name]), 
        
                 nameSlug: propertiesSlugs[name] 
        
               } ]); 
        
             } 
        
             //patterns properties 
        
             for (let i=0; i<_.keys(schema.patternProperties).length;i++) { 
        
               const name = _.keys(schema.patternProperties)[i]; 
        
               multi.push( [ 'pattern-property.ejs', { 
        
                 name: name, 
        
                 examples: stringifyExamples(schema.patternProperties[name]['examples']), 
        
                 ejs: ejsRender, 
        
                 schema: simpletype(schema.patternProperties[name]) } ]); 
        
             } 
        
           }

for definition

jsonschema2md/lib/markdownWriter.js

Lines 203 to 241 in 74db566

    
           //find definitions that contain properties that are not part of the main schema 
        
           if (_.keys(schema.definitions).length > 0) { 
        
             const abstract = {}; 
        
             for (let i=0; i<_.keys(schema.definitions).length;i++) { 
        
               if (schema.definitions[_.keys(schema.definitions)[i]].properties!==undefined) { 
        
                 const definition = schema.definitions[_.keys(schema.definitions)[i]].properties; 
        
                 for (let j=0; j<_.keys(definition).length;j++) { 
        
                   const name = _.keys(definition)[j]; 
        
                   const property = definition[_.keys(definition)[j]]; 
        
                   //console.log('Checking ' + name + ' against ' + _.keys(schema.properties)); 
        
                   if (_.keys(schema.properties).indexOf(name)===-1) { 
        
                     property.definitiongroup = _.keys(schema.definitions)[i]; 
        
                     abstract[name] = property; 
        
                   } 
        
                 } 
        
               } 
        
             } 
        
             propertiesSlugs = createGithubSlugs(_.keys(abstract)); 
        
             if (_.keys(abstract).length>0) { 
        
               //console.log('I got definitions!', abstract); 
        
               multi.push([ 'definitions.ejs', { 
        
                 props: requiredProperties(abstract), 
        
                 title: schema.title, 
        
                 id: schema.$id, 
        
                 propertiesSlugs:propertiesSlugs 
        
               } ]); 
        
               for (let i=0; i<_.keys(abstract).length;i++) { 
        
                 const name = _.keys(abstract).sort()[i]; 
        
                 multi.push( [ 'property.ejs', { 
        
                   name: name, 
        
                   required: false, 
        
                   ejs: ejsRender, 
        
                   examples: stringifyExamples(abstract[name]['examples']), 
        
                   schema: simpletype(abstract[name]), 
        
                   nameSlug: propertiesSlugs[name] 
        
                 } ]); 
        
               } 
        
             } 
        
           }

bryanculver · 2019-04-09T17:52:34Z

So I was digging into this and wanted to better understand the expected outcome. I slightly changed your example to this:

{
  "$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,
  "oneOf": [
    { "$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#" }
  ] 
}

Which resulted in:


  # 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 | [test.schema.json](test.schema.json) |


**One** of the following *conditions* need to be fulfilled.


#### Condition 1


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


#### Condition 2


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


#### Condition 3


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


#### Condition 4


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


#### Condition 5


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


#### Condition 6


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


#### Condition 7


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


#### Condition 8


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


#### Condition 9


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


#### Condition 10


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


#### Condition 11


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


#### Condition 12


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


#### Condition 13


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


#### Condition 14


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


#### Condition 15


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


#### Condition 16


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


#### Condition 17


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


#### Condition 18


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


#### Condition 19


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


#### Condition 20


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


#### Condition 21


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


#### Condition 22


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


#### Condition 23


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

AndyOGo · 2019-04-09T18:48:46Z

Thanks, please see my comment for all failing features at the root level:
#73 (comment)

BREAKING CHANGE: fixes #126, fixes #174, fixes #72, fixes #73, fixes #94, fixes #52, fixes #20, fixes #125, fixes #177, fixes #34, closes #123

# [4.0.0](v3.3.1...v4.0.0) (2019-12-16) ### Bug Fixes * **i18n:** use correct file name format ([43a74f4](43a74f4)) * **markdown:** constraint values can be zero now ([2e057fd](2e057fd)) * **markdown:** handle null as a constant value ([e652e11](e652e11)) * **proxy:** remove logging statements ([616a1d9](616a1d9)) * **schemas:** remove references going nowhere ([2186142](2186142)) ### Build System * **dependencies:** remove unused dependencies ([dbc9192](dbc9192)) ### Code Refactoring * **cli:** remove bluebird, lodash, simplify arg parsing ([b6b1822](b6b1822)) ### Continuous Integration * **test:** require node 10 ([ba4a947](ba4a947)) ### Documentation * **changelog:** mention changes for v4 ([4dfe90c](4dfe90c)), closes [#126](#126) [#174](#174) [#72](#72) [#73](#73) [#94](#94) [#52](#52) [#20](#20) [#125](#125) [#177](#177) [#34](#34) [#123](#123) ### Features * **cli:** generate JSON schema output ([dd18f3b](dd18f3b)), closes [#176](#176) * **formats:** add support for formats: json-pointer, relative-json-pointer, regex, and uri-template ([689c158](689c158)) * **i18n:** new internationalization system ([1a664de](1a664de)) * **i18n:** provide complete en_US translation ([5eb0c89](5eb0c89)) * **markdown:** add header surpression ([6225b9f](6225b9f)) * **markdown:** add support for `default` keyword ([72a0fde](72a0fde)) * **markdown:** add support for comments ([07bb52f](07bb52f)) * **markdown:** add YAML frontmatter support ([4df92e6](4df92e6)) * **markdown:** create and write markdown ([e521541](e521541)) * **markdown:** generate additional detail ([cc07df2](cc07df2)) * **markdown:** generate header again ([011427c](011427c)) * **markdown:** generate some property details ([fa34cf1](fa34cf1)) * **markdown:** generate type details ([c9f19e1](c9f19e1)) * **markdown:** highlight keyword usage for documentation ([d35e4ed](d35e4ed)), closes [#100](#100) * **markdown:** list nested schemas in README ([608674b](608674b)) * **markdown:** list nested schemas in README ([87e8489](87e8489)) * **markdown:** show examples ([c8e8dfa](c8e8dfa)) * **markdown:** show extensibility and abstraction in header ([90a9a8e](90a9a8e)) * **markdown:** show id and status in header ([08e1923](08e1923)) * **markdown:** show id and status in header ([b6fcf53](b6fcf53)) * **markdown:** show join types ([12af018](12af018)) * **markdown:** show some info about properties, switch i18n library ([f8a32df](f8a32df)) * **markdown:** show type, link, additional and custom properties in header ([eff129a](eff129a)) * **markdown:** show value constraints ([515969c](515969c)) * **markdown:** support item arrays and additionalItems ([c9fbcdf](c9fbcdf)), closes [#31](#31) * **markdown:** support patternProperties and additionalProperties ([1386ee3](1386ee3)), closes [#95](#95) [#180](#180) * **proxy:** generate meta information ([ac65ac6](ac65ac6)) * **proxy:** generate slugs ([eacbf38](eacbf38)) * **proxy:** resolve references ([4cea068](4cea068)) * **readme:** generate readme again ([d6b9e5e](d6b9e5e)) * **readme:** mention the most common schema version ([fc583d7](fc583d7)) * **schema:** add full support for "A Vocabulary for the Contents of String-Encoded Data" ([96ca3a6](96ca3a6)) * **schema:** add support for keyword `$defs` ([70b63c8](70b63c8)) * **schema:** add support for keyword `deprecated` ([934b856](934b856)) * **schema:** add support for readOnly and writeOnly schemas and properties ([7452882](7452882)) ### BREAKING CHANGES * **changelog:** * **i18n:** The file format for the i18n files has changed You can now specify the language to use using `-l` and `jsonschema2md` will pick up the correct language configuration. * **test:** Node 8 is no longer supported * **dependencies:** Removes the JSON schema validation feature entirely * **cli:** Repaces lodash with ferrum, removed bluebird, changes the meaning of `--schema-out` or `-x` to be no longer relative to output dir The `--schema-out` or `-x` command line option is no longer relative to the output path (specified with `-o` or `--out`)

trieloff · 2019-12-16T14:54:03Z

🎉 This issue has been resolved in version 4.0.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

AndyOGo · 2019-12-16T15:16:47Z

awesome, can't wait to use it

AndyOGo mentioned this issue Jun 5, 2018

refs in items of array do not work at root level #72

Closed

trieloff mentioned this issue Dec 11, 2019

V2 rewrite #181

Merged

7 tasks

trieloff added a commit that referenced this issue Dec 16, 2019

docs(changelog): mention changes for v4

4dfe90c

BREAKING CHANGE: fixes #126, fixes #174, fixes #72, fixes #73, fixes #94, fixes #52, fixes #20, fixes #125, fixes #177, fixes #34, closes #123

trieloff closed this as completed in #181 Dec 16, 2019

trieloff added the released label Dec 16, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Am I correct that the root type can only be object? #73

Am I correct that the root type can only be object? #73

AndyOGo commented May 24, 2018

AndyOGo commented May 24, 2018 •

edited

Loading

AndyOGo commented Jun 5, 2018

AndyOGo commented Jun 19, 2018

bryanculver commented Apr 9, 2019

bryanculver commented Apr 9, 2019

AndyOGo commented Apr 9, 2019

trieloff commented Dec 16, 2019

AndyOGo commented Dec 16, 2019

Am I correct that the root type can only be object? #73

Am I correct that the root type can only be object? #73

Comments

AndyOGo commented May 24, 2018

What did you do

What did you expect to happen

What happened

What's your environment

Do you have example files:

AndyOGo commented May 24, 2018 • edited Loading

AndyOGo commented Jun 5, 2018

AndyOGo commented Jun 19, 2018

bryanculver commented Apr 9, 2019

bryanculver commented Apr 9, 2019

AndyOGo commented Apr 9, 2019

trieloff commented Dec 16, 2019

AndyOGo commented Dec 16, 2019

AndyOGo commented May 24, 2018 •

edited

Loading