Documentation for Iglu Central

What did you do

I am trying to generate documentations for snowplow/iglu-central: https://github.com/snowplow/iglu-central/tree/master/schemas

Since Snowplow schemas have no file extension, (i.e. 1-0-0) I had to add the extension myself:

mkdir input
cd input && git clone https://github.com/snowplow/iglu-central.git 
find . -type f -name '*-*-*'  -exec sh -c 'x="{}"; mv "$x" "${x}.schema.json"' \;

cd .. 
node cli.js -d input/iglu-central/schemas -o output -v 04

Then it gave me this error:

node cli.js -d input/iglu-central/schemas -o output -v 04                     
4
info: output directory: jsonschema2md/output
error: Ajv processing error for schema at path jsonschema2md/input/iglu-central/schemas/com.adjust/install/jsonschema/1-0-0.schema.json
error: no schema with key or ref "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#"

So I had to replace the main schema file path and I decided to have local address because I could not change the one on Iglu Server:

find . -name '*.schema.json' | xargs sed -i .bak 's/http:\/\/iglucentral.com\/schemas\/com.snowplowanalytics.self-desc\/schema\/jsonschema\/1-0-0#/com.snowplowanalytics.self-desc\/schema\/jsonschema\/1-0-0.schema.json/g'

Again, I have the same problem, so probably my solution was not right. This is the error message:

node cli.js -d input/iglu-central/schemas -o output -v 04                                                                                   
4
info: output directory: jsonschema2md/output
error: Ajv processing error for schema at path jsonschema2md/input/iglu-central/schemas/com.adjust/install/jsonschema/1-0-0.schema.json
error: no schema with key or ref "com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0.schema.json"

What did you expect to happen

The documentation to be generated

What happened

It didn't work. I have pasted the errors above.

What's your environment

Operating System: MacOS
node.js version: 10.12.0

Do you have example files:

https://github.com/snowplow/iglu-central/blob/master/schemas/com.adjust/install/jsonschema/1-0-0

@szareiangm Did you ever figure out a workaround for this issue? I have exactly the same problem.

BTW - I'm using SchemaVer and wanted to say thank you!

UPDATE

Turns out it was a case of not paying close attention to the documentation. You have to pass in the metaschema as a separate argument. This mostly worked for me:

jsonschema2md --metaSchema schemas/metaschema/1-0-0.schema.json -d schemas/error/1-0-0.schema.json

I still hit another Error can't resolve reference http://json-schema.org/draft/2019-09/schema# from id https://schemas.tf/json/metaschema/1-0-0#. But after I referenced the metaschema, I was able to generate the markdown files without any problems.

I opened another issue #178 to see if jsonschema2md can dereference schemas before parsing.

adobe / jsonschema2md